Skip to content

HaiyiMei/scorestarling-plugins / skills/scorestarling-arrange-for-level

scorestarling-arrange-for-level

Verified

Arrange or simplify a piece for a chosen instrument at a chosen level, then check it lands there. Routes across piano, violin, viola, cello, double bass, flute, oboe, clarinet, bassoon, saxophone, recorder, trumpet, trombone, horn, classical and pop guitar, ukulele, voice, drums and the Chinese erhu, guzheng and dizi, from beginner to Grade 8 (Chinese instruments to 10), with the level as an ABRSM, Trinity, RCM, AMEB or Chinese 考级 number or in plain words (beginner, easy, 初学, 入门). Use whenever someone wants an easier, graded or "playable for my student or child" version of a piece for a particular instrument ("Grade 3 piano", "英皇五级小提琴", "尤克里里弹唱简单版", "古筝三级", "flute version for a year-two player"), wants a part fitted to a learner's level, or asks whether a score is really at some grade, even if they never say "arrange". If the instrument or the level is missing, ask one short question with options instead of guessing. Not for faithful transcriptions or for tidying a score without making it easier.

FileKindSize
SKILL.mdskill md17.2 KB
evals/evals.jsonconfig18.8 KB
references/instruments/bassoon.mdmarkdown3.1 KB
references/instruments/cello.mdmarkdown17.6 KB
references/instruments/clarinet.mdmarkdown11.4 KB
references/instruments/classical-guitar.mdmarkdown10.9 KB
references/instruments/dizi.mdmarkdown10.7 KB
references/instruments/double-bass.mdmarkdown3.9 KB
references/instruments/drums.mdmarkdown12.5 KB
references/instruments/erhu.mdmarkdown11.2 KB
references/instruments/flute.mdmarkdown11.7 KB
references/instruments/guzheng.mdmarkdown10.1 KB
references/instruments/horn.mdmarkdown9.9 KB
references/instruments/oboe.mdmarkdown10.1 KB
references/instruments/piano.mdmarkdown11.4 KB
references/instruments/pop-guitar.mdmarkdown12.9 KB
references/instruments/recorder.mdmarkdown11.9 KB
references/instruments/saxophone.mdmarkdown11.2 KB
references/instruments/trombone.mdmarkdown10.5 KB
references/instruments/trumpet.mdmarkdown11.6 KB
references/instruments/ukulele.mdmarkdown10.6 KB
references/instruments/viola.mdmarkdown9.7 KB
references/instruments/violin.mdmarkdown17.5 KB
references/instruments/voice.mdmarkdown12.8 KB
references/levels.mdmarkdown7.7 KB
references/other-instruments.mdmarkdown6.0 KB
references/profiles/bassoon.jsonconfig3.7 KB
references/profiles/cello.jsonconfig3.7 KB
references/profiles/clarinet.jsonconfig3.7 KB
references/profiles/classical-guitar.jsonconfig3.4 KB
references/profiles/descant-recorder.jsonconfig3.3 KB
references/profiles/dizi.jsonconfig4.5 KB
references/profiles/double-bass.jsonconfig4.0 KB
references/profiles/drums.jsonconfig2.5 KB
references/profiles/erhu.jsonconfig4.7 KB
references/profiles/flute.jsonconfig3.6 KB
references/profiles/guzheng.jsonconfig5.0 KB
references/profiles/horn.jsonconfig3.9 KB
references/profiles/oboe.jsonconfig3.7 KB
references/profiles/piano.jsonconfig6.2 KB
references/profiles/pop-guitar.jsonconfig3.1 KB
references/profiles/saxophone.jsonconfig3.9 KB
references/profiles/treble-recorder.jsonconfig4.1 KB
references/profiles/trombone.jsonconfig3.9 KB
references/profiles/trumpet.jsonconfig3.7 KB
references/profiles/ukulele.jsonconfig4.1 KB
references/profiles/viola.jsonconfig3.7 KB
references/profiles/violin.jsonconfig3.7 KB
references/profiles/voice.jsonconfig3.5 KB
references/sources.mdmarkdown12.5 KB
scripts/check_level.pyscript34.8 KB

scripts/check_level.py

View on GitHub
#!/usr/bin/env python3
"""Check a MusicXML score against the level profile of an instrument and grade.

Usage:
  python3 check_level.py score.musicxml --instrument piano --grade 2 [--json] [--mark marked.musicxml]
  python3 check_level.py score.musicxml --instrument violin --estimate
  python3 check_level.py --list

Profiles live in ../references/profiles/<instrument>.json (see ../references/levels.md for where each
number comes from). Prints one line per check (ok / warn / over / info) with bar numbers, then a
verdict. --estimate runs every grade of the profile and reports the lowest one with nothing over.
--mark writes a copy with every note that broke a check coloured red, for a before/after picture.
Standard library only; reads .musicxml, .xml and .mxl. It measures notation, not musicianship: a
clean result does not prove the melody survived or that the piece sounds good, so listen and
compare as well.
"""
import argparse
import json
import sys
import xml.etree.ElementTree as ET
import zipfile
from collections import defaultdict
from fractions import Fraction
from pathlib import Path

STEPS = {'C': 0, 'D': 2, 'E': 4, 'F': 5, 'G': 7, 'A': 9, 'B': 11}
SHORT_TYPES = {'16th', '32nd', '64th', '128th'}
TINY_TYPES = {'32nd', '64th', '128th'}
RED = '#D0021B'
PROFILES = Path(__file__).resolve().parent.parent / 'references' / 'profiles'
DEFAULT_TEMPO = 96.0


def load(path):
    if path.endswith('.mxl'):
        with zipfile.ZipFile(path) as z:
            names = [n for n in z.namelist() if not n.startswith('META-INF') and n.endswith(('.xml', '.musicxml'))]
            return ET.ElementTree(ET.fromstring(z.read(names[0])))
    return ET.parse(path)


def text(el, path, default=None):
    found = el.find(path)
    return found.text.strip() if found is not None and found.text else default


class Note:
    def __init__(self, el, bar, onset, dur, hand, voice):
        self.el, self.bar, self.onset, self.dur, self.hand, self.voice = el, bar, onset, dur, hand, voice
        self.midi = None
        pitch = el.find('pitch')
        if pitch is not None:
            self.midi = (int(text(pitch, 'octave')) + 1) * 12 + STEPS[text(pitch, 'step')] + int(float(text(pitch, 'alter', '0')))
        unpitched = el.find('unpitched')
        inst = el.find('instrument')
        self.inst = inst.get('id') if inst is not None else (
            f"{text(unpitched, 'display-step')}{text(unpitched, 'display-octave')}" if unpitched is not None else None)
        self.type = text(el, 'type')
        self.dots = len(el.findall('dot'))
        self.tuplet = el.find('time-modification') is not None
        self.grace = el.find('grace') is not None
        self.tied_from = any(t.get('type') == 'stop' for t in el.findall('tie'))
        # a breath mark or caesura on a note means the player breathes right after it
        self.breath_after = el.find('notations/articulations/breath-mark') is not None or el.find('notations/articulations/caesura') is not None


def read_score(tree, kind, part_number=1):
    root = tree.getroot()
    parts = root.findall('part')
    notes = []
    info = {'keys': [], 'times': [], 'clef_changes': [], 'pedal': [], 'octave_shift': [], 'tempo': [],
            'bars': 0, 'quarters': Fraction(0), 'parts': len(parts), 'has_transpose': False}
    if kind == 'keyboard':
        two_parts = len(parts) >= 2 and all(p.find('measure/attributes/staves') is None for p in parts[:2])
        chosen = parts[:2] if two_parts else parts[:1]
    else:
        two_parts = False
        chosen = [parts[min(part_number, len(parts)) - 1]]
    for p_index, part in enumerate(chosen):
        divisions = 1
        bar_count = 0
        clefs_seen = {}
        start = Fraction(0)
        for m_index, measure in enumerate(part.findall('measure')):
            bar = m_index + 1
            bar_count = bar
            pos = Fraction(0)
            longest = Fraction(0)
            last_onset = Fraction(0)
            for el in measure:
                if el.tag == 'attributes':
                    divisions = int(text(el, 'divisions', divisions))
                    if el.find('transpose') is not None:
                        info['has_transpose'] = True
                    for key in el.findall('key'):
                        if p_index == 0:
                            info['keys'].append((bar, int(text(key, 'fifths', '0')), text(key, 'mode', 'major')))
                    for time in el.findall('time'):
                        if p_index == 0:
                            info['times'].append((bar, f"{text(time, 'beats')}/{text(time, 'beat-type')}"))
                    for clef in el.findall('clef'):
                        staff = clef.get('number', str(p_index + 1))
                        sign = text(clef, 'sign')
                        if staff in clefs_seen and clefs_seen[staff] != sign:
                            info['clef_changes'].append(bar)
                        clefs_seen[staff] = sign
                elif el.tag == 'direction':
                    if el.find('direction-type/pedal') is not None:
                        info['pedal'].append(bar)
                    shift = el.find('direction-type/octave-shift')
                    if shift is not None and shift.get('type') != 'stop':
                        info['octave_shift'].append(bar)
                    sound = el.find('sound')
                    if sound is not None and sound.get('tempo'):
                        info['tempo'].append((bar, float(sound.get('tempo'))))
                elif el.tag == 'backup':
                    pos -= Fraction(int(text(el, 'duration', '0')), divisions)
                elif el.tag == 'forward':
                    pos += Fraction(int(text(el, 'duration', '0')), divisions)
                elif el.tag == 'note':
                    dur = Fraction(int(text(el, 'duration', '0')), divisions)
                    chord = el.find('chord') is not None
                    onset = last_onset if chord else pos
                    staff = text(el, 'staff', '1')
                    if kind == 'keyboard':
                        hand = ('RH' if p_index == 0 else 'LH') if two_parts else ('RH' if staff == '1' else 'LH')
                    else:
                        hand = 'line'
                    if el.find('rest') is None:
                        note = Note(el, bar, (bar, onset), dur, hand, text(el, 'voice', '1'))
                        note.time = start + onset
                        notes.append(note)
                    if not chord:
                        last_onset = pos
                        pos += dur
                longest = max(longest, pos)
            start += longest
        info['bars'] = max(info['bars'], bar_count)
        if p_index == 0:
            info['quarters'] = start
    return notes, info


# --- profiles -----------------------------------------------------------------------------------

def profile_files():
    return sorted(PROFILES.glob('*.json'))


def load_profile(name):
    wanted = name.lower().strip().replace(' ', '-')
    for path in profile_files():
        data = json.loads(path.read_text(encoding='utf-8'))
        names = [data['instrument']] + data.get('aliases', [])
        if wanted in [n.lower().replace(' ', '-') for n in names]:
            return data
    sys.exit(f'No profile for "{name}". Available: ' + ', '.join(
        json.loads(p.read_text(encoding='utf-8'))['instrument'] for p in profile_files()))


def grade_key(profile, grade):
    keys = list(profile['grades'])
    if str(grade) in keys:
        return str(grade)
    sys.exit(f'{profile["instrument"]} has no grade "{grade}". Available: ' + ', '.join(keys))


def grade_label(profile, key):
    names = profile.get('grade_names', {})
    return names.get(key) or f'{profile.get("grade_word", "Grade")} {key}'


# --- helpers ------------------------------------------------------------------------------------

def bars_of(items):
    bars = sorted({n.bar for n in items})
    if len(bars) > 8:
        return ', '.join(map(str, bars[:8])) + f' … ({len(bars)} bars)'
    return ', '.join(map(str, bars))


def name_of(midi):
    return ['C', 'C#', 'D', 'Eb', 'E', 'F', 'F#', 'G', 'Ab', 'A', 'Bb', 'B'][midi % 12] + str(midi // 12 - 1)


def key_scale(fifths):
    tonic = (7 * fifths) % 12
    major = {(tonic + i) % 12 for i in (0, 2, 4, 5, 7, 9, 11)}
    # Allow the raised 7th of the relative minor (harmonic minor), common at low grades.
    return major | {(tonic + 8) % 12}


def window_shifts(seq, window):
    """Greedy count of new hand positions: one position covers `window` semitones."""
    shifts, lo, hi, where = 0, None, None, []
    for n in seq:
        if lo is None:
            lo = hi = n.midi
            continue
        new_lo, new_hi = min(lo, n.midi), max(hi, n.midi)
        if new_hi - new_lo > window:
            shifts += 1
            where.append(n.bar)
            lo = hi = n.midi
        else:
            lo, hi = new_lo, new_hi
    return shifts, where


def fifths_for_tonic(pc):
    """Key signature (as a count of sharps, negative for flats) of the major key on pitch class pc."""
    return min((f for f in range(-6, 7) if (7 * f) % 12 == pc), key=abs)


def to_written(notes, info, offset):
    """Shift concert-pitch notes and key signatures up by `offset` semitones to written pitch."""
    for n in notes:
        if n.midi is not None:
            n.midi += offset
    info['keys'] = [(bar, fifths_for_tonic(((7 * f) + offset) % 12), mode) for bar, f, mode in info['keys']]


def tempo_of(info):
    if info['tempo']:
        return info['tempo'][0][1], False
    return DEFAULT_TEMPO, True


def runs_of(notes, gap):
    """Unbroken stretches of sound: consecutive notes with less than `gap` quarters of rest between, and a breath mark or caesura ends a stretch."""
    runs, cur, end = [], [], None
    for n in sorted(notes, key=lambda n: n.time):
        if cur and n.time - end >= gap:
            runs.append(cur)
            cur, end = [], None
        cur.append(n)
        stop = n.time + n.dur
        end = stop if end is None else max(end, stop)
        if n.breath_after:
            runs.append(cur)
            cur, end = [], None
    if cur:
        runs.append(cur)
    return runs


# --- checks -------------------------------------------------------------------------------------

class Report:
    def __init__(self, ignore=()):
        self.results, self.flagged, self.ignore = [], set(), set(ignore)

    def add(self, name, status, detail, bad=()):
        if name in self.ignore:
            self.results.append({'check': name, 'status': 'info', 'detail': f'(ignored) {detail}'})
            return
        self.results.append({'check': name, 'status': status, 'detail': detail})
        for n in bad:
            self.flagged.add(id(n.el))


def band(value, ok_max, warn_max):
    return 'ok' if value <= ok_max else ('warn' if value <= warn_max else 'over')


def check_common(notes, info, g, next_g, rep, kind):
    bars = info['bars']
    pitched = [n for n in notes if n.midi is not None]
    # Key
    keys = info['keys'] or [(1, 0, 'major')]
    first = keys[0]
    if g.get('key_sigs') is not None and kind != 'percussion':
        allowed = set(g['key_sigs'])
        worst = 'ok'
        for _, f, _ in keys:
            if f in allowed:
                continue
            near = any(abs(f - a) == 1 for a in allowed)
            worst = 'over' if worst == 'over' or not near else 'warn'
        listed = ', '.join((f'{abs(a)} {"sharp" if a > 0 else "flat"}' + ('s' if abs(a) > 1 else '')) if a else 'none' for a in sorted(allowed))
        rep.add('key', worst, f'{abs(first[1])} {"sharp" if first[1] > 0 else "flat"}{"s" if abs(first[1]) != 1 else ""} ({first[2]})'
                if first[1] else f'no sharps or flats ({first[2]})', ())
        rep.results[-1]['detail'] += f'; key signatures this level reads: {listed}'
        if len({k[1] for k in keys}) > 1:
            rep.add('key changes', 'warn', 'key changes at bars ' + ', '.join(str(k[0]) for k in keys[1:]))
    elif g.get('key_max_acc') is not None and kind != 'percussion':
        worst = max(abs(k[1]) for k in keys)
        limit = g['key_max_acc']
        rep.add('key', 'ok' if worst <= limit else ('warn' if worst == limit + 1 else 'over'),
                f'{abs(first[1])} {"sharp" if first[1] > 0 else "flat"}{"s" if abs(first[1]) != 1 else ""} ({first[2]}); '
                f'this level uses at most {limit}' if first[1] else f'no sharps or flats ({first[2]}); this level uses at most {limit}')
        if len({k[1] for k in keys}) > 1:
            rep.add('key changes', 'warn', 'key changes at bars ' + ', '.join(str(k[0]) for k in keys[1:]))
    # Meter
    times = info['times'] or [(1, '4/4')]
    if g.get('meters'):
        status = 'ok'
        for _, t in times:
            if t in g['meters']:
                continue
            nxt = (next_g or {}).get('meters')
            status = 'over' if status == 'over' or not nxt or t not in nxt else 'warn'
        rep.add('time signature', status, ', '.join(dict.fromkeys(t for _, t in times)) +
                ('' if status == 'ok' else f'; this level uses {", ".join(g["meters"])}'))
    if len({t[1] for t in times}) > 1:
        rep.add('time changes', 'warn', 'meter changes at bars ' + ', '.join(str(t[0]) for t in times[1:]))
    # Length
    if g.get('bars'):
        lo, hi = g['bars']
        rep.add('length', 'ok' if lo <= bars <= hi else 'warn', f'{bars} bars (this level is usually {lo}–{hi})')
    # Rhythm
    ok_share = g.get('sixteenth_share_ok')
    if ok_share is not None:
        if ok_share == 0:
            short = [n for n in notes if n.type in SHORT_TYPES or (n.type == 'eighth' and n.dots)]
            rep.add('shortest notes', 'over' if short else 'ok',
                    f'{len(short)} notes shorter than an eighth (or dotted eighths), bars {bars_of(short)}' if short
                    else 'eighths or longer', short)
        else:
            short = [n for n in notes if n.type in SHORT_TYPES]
            share = len(short) / max(1, len(notes))
            status = band(share, ok_share, ok_share + 0.25)
            rep.add('shortest notes', status, f'{share:.0%} of notes are sixteenths or shorter (this level up to {ok_share:.0%})',
                    short if status != 'ok' else ())
    tiny = [n for n in notes if n.type in TINY_TYPES]
    if tiny and g.get('thirty_seconds'):
        rep.add('32nd notes', g['thirty_seconds'], f'{len(tiny)} notes of 32nd or shorter, bars {bars_of(tiny)}',
                tiny if g['thirty_seconds'] != 'ok' else ())
    tup = [n for n in notes if n.tuplet]
    if tup and g.get('triplets', 'ok') != 'ok':
        rep.add('tuplets', g['triplets'], f'{len(tup)} tuplet notes, bars {bars_of(tup)}', tup)
    grace = [n for n in notes if n.grace]
    if grace and g.get('grace', 'ok') != 'ok':
        rep.add('grace notes', g['grace'], f'{len(grace)} grace notes, bars {bars_of(grace)}', grace)
    # Accidentals outside the key
    per_bar = g.get('accidentals_per_bar')
    if per_bar is not None and pitched:
        scale = key_scale((info['keys'] or [(1, 0, 'major')])[0][1])
        acc = [n for n in pitched if (n.midi % 12) not in scale]
        limit = max(2, per_bar * bars)
        rep.add('accidentals', 'ok' if len(acc) <= limit else 'warn',
                f'{len(acc)} notes outside the key signature (this level about {per_bar:g} a bar)',
                acc if len(acc) > limit else ())
    # Notation features
    for field, key, label in (('pedal', 'pedal', 'pedal'), ('ottava', 'octave_shift', 'octave lines'),
                              ('clef_change', 'clef_changes', 'clef changes')):
        status = g.get(field)
        if status and status != 'ok' and info[key]:
            where = ', '.join(map(str, sorted(set(info[key]))))
            rep.add(label, status, f'{label} at bars {where}; not expected at this level')
    # Tempo and density
    tempo, assumed = tempo_of(info)
    if g.get('tempo_max') and info['tempo']:
        fast = max(t for _, t in info['tempo'])
        rep.add('tempo', 'ok' if fast <= g['tempo_max'] else 'warn',
                f'up to {fast:g} quarter notes a minute (this level up to {g["tempo_max"]})')


def density(notes, info, profile, key):
    """Notes per second against recordings labelled with this grade (PSyllabus), piano only."""
    dens = profile.get('density')
    if not dens or not info['quarters']:
        return None
    counted = [n for n in notes if not n.grace and not n.tied_from]
    tempo, assumed = tempo_of(info)
    seconds = float(info['quarters']) * 60 / tempo
    rate = len(counted) / seconds
    lo, mid, hi = dens['notes_per_s'][key]
    dur_lo, dur_mid, dur_hi = dens['duration_s'][key]
    tail = f' (tempo {"assumed " if assumed else ""}{tempo:g})'
    status = 'warn' if rate > hi else 'info'
    detail = (f'{rate:.1f} notes a second{tail}; recordings at this grade: median {mid}, 90% under {hi}. '
              f'Length about {seconds:.0f} s without repeats; typical {dur_lo:.0f}–{dur_hi:.0f} s, median {dur_mid:.0f}')
    return status, detail


def check_keyboard(notes, info, g, rep):
    bars = info['bars']
    for hand in ('RH', 'LH'):
        hn = [n for n in notes if n.hand == hand and not n.grace and n.midi is not None]
        if not hn:
            rep.add(f'{hand} present', 'warn', f'no {hand} notes')
            continue
        by_onset = defaultdict(list)
        for n in hn:
            by_onset[n.onset].append(n)
        onsets = sorted(by_onset)
        stacks = [by_onset[o] for o in onsets]
        struck = [[n for n in s if not n.tied_from] for s in stacks]
        # Notes at once
        over_at, warn_at = g.get('chord_over_at'), g.get('chord_warn_at')
        if over_at:
            big = [s for s in struck if len(s) >= over_at]
            if big:
                rep.add(f'{hand} notes at once', 'over', f'{len(big)} chords of {over_at}+ notes, bars {bars_of([s[0] for s in big])}',
                        [n for s in big for n in s])
        if warn_at and not (over_at and any(len(s) >= over_at for s in struck)):
            many = [s for s in struck if len(s) >= warn_at]
            share = len(many) / max(1, len(stacks))
            limit = g.get('chord_warn_share', 1.0)
            rep.add(f'{hand} notes at once', 'ok' if share <= limit else 'warn',
                    f'at most {max([len(s) for s in struck] or [1])}; {warn_at}+ notes together on {share:.0%} of onsets'
                    + ('' if share <= limit else ' (keep them occasional)'),
                    [n for s in many for n in s] if share > limit else ())
        # Stretch of notes struck together
        if g.get('stretch'):
            sw, so = g['stretch']
            wide = [s for s in struck if len(s) >= 2 and max(n.midi for n in s) - min(n.midi for n in s) > sw]
            if wide:
                over = [s for s in wide if max(n.midi for n in s) - min(n.midi for n in s) > so]
                rep.add(f'{hand} stretch', 'over' if over else 'warn',
                        f'{len(wide)} chords or intervals wider than {sw} semitones, bars {bars_of([s[0] for s in wide])}',
                        [n for s in wide for n in s])
        if g.get('voices_warn'):
            voices = {n.voice for n in hn}
            if len(voices) > 1:
                rep.add(f'{hand} voices', 'warn', f'{len(voices)} voices in one hand; this level has one line per hand')
        # Range and leaps (top line for RH, bottom line for LH)
        line = [max(s, key=lambda n: n.midi) if hand == 'RH' else min(s, key=lambda n: n.midi) for s in stacks]
        lo, hi = min(n.midi for n in hn), max(n.midi for n in hn)
        if g.get('hand_span'):
            ws, wo = g['hand_span']
            rep.add(f'{hand} range', band(hi - lo, ws, wo), f'{name_of(lo)}–{name_of(hi)} ({hi - lo} semitones; comfortable up to {ws})')
        if g.get('leap'):
            lw, lo_over = g['leap']
            # A jump after a rest or a long note (half or longer) gives the hand time to move,
            # so only count jumps between connected notes.
            joined = [(a, b) for a, b in zip(line, line[1:]) if a.dur < 2 and b.time <= a.time + a.dur]
            leaps = [b for a, b in joined if abs(b.midi - a.midi) > lo_over]
            mid = [b for a, b in joined if lw < abs(b.midi - a.midi) <= lo_over]
            if leaps:
                rep.add(f'{hand} leaps', 'over', f'{len(leaps)} jumps over {lo_over} semitones between connected notes, bars {bars_of(leaps)}', leaps)
            elif len(mid) > max(2, bars // 8):
                rep.add(f'{hand} leaps', 'warn', f'{len(mid)} jumps over {lw} semitones, bars {bars_of(mid)}', mid)
        if g.get('ledger'):
            low_lim, high_lim = (g['ledger'][0], g['ledger'][1]) if hand == 'RH' else (g['ledger'][2], g['ledger'][3])
            ledger = [n for n in hn if n.midi < low_lim or n.midi > high_lim]
            if len(ledger) > max(2, len(hn) // 20):
                rep.add(f'{hand} ledger lines', 'warn', f'{len(ledger)} notes beyond one ledger line, bars {bars_of(ledger)}', ledger)
        if g.get('positions8') and g.get('position_window'):
            shifts, _ = window_shifts(line, g['position_window'])
            per8 = shifts / max(1, bars) * 8
            ws, wo = g['positions8']
            rep.add(f'{hand} hand positions', band(per8, ws, wo), f'{shifts} moves out of a {g["position_window"]}-semitone position ({per8:.1f} per 8 bars)')
        if hand == 'LH' and g.get('lh_pace'):
            quick = [s[0] for s in stacks if s[0].dur < 1]
            share_q = len(quick) / len(stacks)
            ws, wo = g['lh_pace']
            rep.add('LH pace', band(share_q, ws, wo), f'{share_q:.0%} of LH onsets are eighths or shorter (this level up to {ws:.0%})',
                    quick if share_q > ws else ())
    if g.get('both_eighths_per_bar'):
        rh_q = {n.onset for n in notes if n.hand == 'RH' and n.dur < 1}
        lh_q = {n.onset for n in notes if n.hand == 'LH' and n.dur < 1}
        both = rh_q & lh_q
        if len(both) > max(4, bars * g['both_eighths_per_bar']):
            rep.add('hands together in eighths', 'warn', f'{len(both)} eighth-note onsets in both hands at once')


def check_line(notes, info, g, rep, profile):
    """One melodic part: strings, winds, voice, guitar melody."""
    pitched = [n for n in notes if n.midi is not None and not n.grace]
    if not pitched:
        rep.add('notes', 'warn', 'no pitched notes in this part')
        return
    bars = info['bars']
    by_onset = defaultdict(list)
    for n in pitched:
        by_onset[n.onset].append(n)
    stacks = [by_onset[o] for o in sorted(by_onset)]
    struck = [[n for n in s if not n.tied_from] for s in stacks]
    over_at, warn_at = g.get('chord_over_at'), g.get('chord_warn_at')
    if over_at:
        big = [s for s in struck if len(s) >= over_at]
        if big:
            rep.add('notes at once', 'over', f'{len(big)} places with {over_at}+ notes together, bars {bars_of([s[0] for s in big])}',
                    [n for s in big for n in s])
    if warn_at and not (over_at and any(len(s) >= over_at for s in struck)):
        many = [s for s in struck if len(s) >= warn_at]
        share = len(many) / max(1, len(stacks))
        limit = g.get('chord_warn_share', 0)
        if many:
            rep.add('notes at once', 'ok' if share <= limit else 'warn',
                    f'{warn_at}+ notes together on {share:.0%} of onsets (this level up to {limit:.0%})',
                    [n for s in many for n in s] if share > limit else ())
    if g.get('range'):
        lo_lim, hi_lim = g['range']
        slack = g.get('range_slack', 3)
        out = [n for n in pitched if n.midi < lo_lim or n.midi > hi_lim]
        far = [n for n in out if n.midi < lo_lim - slack or n.midi > hi_lim + slack]
        lo, hi = min(n.midi for n in pitched), max(n.midi for n in pitched)
        status = 'over' if far else ('warn' if out else 'ok')
        rep.add('range', status,
                f'{name_of(lo)}–{name_of(hi)}; this level {name_of(lo_lim)}–{name_of(hi_lim)} (written pitch)' +
                (f'; {len(out)} notes outside, bars {bars_of(out)}' if out else ''), out if out else ())
    if g.get('pitch_classes'):
        free = set(g['pitch_classes'])
        pressed = set(g.get('pitch_classes_pressed', [])) - free
        missing = [n for n in pitched if n.midi % 12 not in free | pressed]
        pressed_notes = [n for n in pitched if n.midi % 12 in pressed]
        if missing:
            rep.add('notes available', 'over', f'{len(missing)} notes the instrument can not play at this level (pitch classes outside its open notes), bars {bars_of(missing)}', missing)
        elif pressed_notes:
            share = len(pressed_notes) / len(pitched)
            limit = g.get('pressed_share_ok', 0)
            rep.add('pressed notes', 'ok' if share <= limit else 'warn',
                    f'{share:.0%} of notes need pressing or bending (this level up to {limit:.0%})', pressed_notes if share > limit else ())
        else:
            rep.add('notes available', 'ok', 'every note is one the instrument plays without pressing or bending')
    if g.get('span'):
        sw, so = g['span']
        lo, hi = min(n.midi for n in pitched), max(n.midi for n in pitched)
        rep.add('span', band(hi - lo, sw, so), f'{name_of(lo)}–{name_of(hi)} ({hi - lo} semitones; this level up to {sw}, a little more is tolerable)')
    if g.get('leap'):
        lw, lo_over = g['leap']
        line = [max(s, key=lambda n: n.midi) for s in stacks]
        joined = [(a, b) for a, b in zip(line, line[1:]) if b.time <= a.time + a.dur]
        leaps = [b for a, b in joined if abs(b.midi - a.midi) > lo_over]
        mid = [b for a, b in joined if lw < abs(b.midi - a.midi) <= lo_over]
        if leaps:
            rep.add('leaps', 'over', f'{len(leaps)} jumps over {lo_over} semitones between connected notes, bars {bars_of(leaps)}', leaps)
        elif len(mid) > max(2, bars // 8):
            rep.add('leaps', 'warn', f'{len(mid)} jumps over {lw} semitones, bars {bars_of(mid)}', mid)
    if g.get('breath_s'):
        tempo, assumed = tempo_of(info)
        ws, wo = g['breath_s']
        runs = runs_of(pitched, Fraction(g.get('breath_gap', 0.5)).limit_denominator(8))
        longest = max(runs, key=lambda r: r[-1].time + r[-1].dur - r[0].time)
        seconds = float(longest[-1].time + longest[-1].dur - longest[0].time) * 60 / tempo
        rep.add('breathing', band(seconds, ws, wo),
                f'longest unbroken phrase about {seconds:.0f} s from bar {longest[0].bar}{" (tempo assumed)" if assumed else ""}; '
                f'this level up to {ws} s (our estimate, not from the syllabus)',
                longest if seconds > ws else ())


def check_percussion(notes, info, g, rep):
    hits = [n for n in notes if not n.grace]
    if not hits:
        rep.add('notes', 'warn', 'no percussion notes in this part')
        return
    by_onset = defaultdict(list)
    for n in hits:
        by_onset[n.onset].append(n)
    stacks = list(by_onset.values())
    if g.get('chord_over_at'):
        big = [s for s in stacks if len(s) >= g['chord_over_at']]
        if big:
            rep.add('hits at once', 'over', f'{len(big)} places with {g["chord_over_at"]}+ drums struck together, bars {bars_of([s[0] for s in big])}',
                    [n for s in big for n in s])
    if g.get('chord_warn_at'):
        many = [s for s in stacks if len(s) >= g['chord_warn_at']]
        share = len(many) / len(stacks)
        if many:
            limit = g.get('chord_warn_share', 1.0)
            rep.add('hits at once', 'ok' if share <= limit else 'warn',
                    f'{g["chord_warn_at"]}+ drums together on {share:.0%} of onsets (this level up to {limit:.0%})',
                    [n for s in many for n in s] if share > limit else ())
    if g.get('instruments_max'):
        used = {n.inst for n in hits}
        rep.add('drums used', 'ok' if len(used) <= g['instruments_max'] else 'warn',
                f'{len(used)} different drums or cymbals (this level up to {g["instruments_max"]})')
    if g.get('hits_per_bar'):
        per_bar = len(hits) / max(1, info['bars'])
        ws, wo = g['hits_per_bar']
        rep.add('density', band(per_bar, ws, wo), f'{per_bar:.1f} hits a bar (this level up to {ws})')


def run_checks(notes, info, profile, key, next_key, ignore=()):
    g = profile['grades'][key]
    next_g = profile['grades'].get(next_key) if next_key else None
    rep = Report(ignore)
    kind = profile['kind']
    check_common(notes, info, g, next_g, rep, kind)
    if kind == 'keyboard':
        check_keyboard(notes, info, g, rep)
    elif kind == 'percussion':
        check_percussion(notes, info, g, rep)
    else:
        check_line(notes, info, g, rep, profile)
    if kind == 'keyboard' and profile.get('density'):
        found = density(notes, info, profile, key)
        if found:
            rep.add('density', *found)
    return rep


def verdict(profile, key, results):
    label = grade_label(profile, key)
    statuses = [r['status'] for r in results]
    if 'over' in statuses:
        return f'above {label}'
    warns = statuses.count('warn')
    if warns > 2:
        return f'close to {label}, with several harder spots'
    return f'about {label}' if not warns else f'about {label}, with a few harder spots'


def grade_order(profile):
    return sorted(profile['grades'], key=lambda k: (not k.lstrip('-').isdigit(), int(k) if k.lstrip('-').isdigit() else 0, k))


def estimate(notes, info, profile, ignore=()):
    order = grade_order(profile)
    rows, lowest, likely = [], None, None
    for i, key in enumerate(order):
        rep = run_checks(notes, info, profile, key, order[i + 1] if i + 1 < len(order) else None, ignore)
        over = [r['check'] for r in rep.results if r['status'] == 'over']
        warn = [r['check'] for r in rep.results if r['status'] == 'warn']
        rows.append({'grade': key, 'label': grade_label(profile, key), 'over': over, 'warn': warn})
        if lowest is None and not over:
            lowest = key
        if likely is None and not over and len(warn) <= 2:
            likely = key
    return rows, lowest, likely


def list_profiles():
    for path in profile_files():
        p = json.loads(path.read_text(encoding='utf-8'))
        print(f"{p['instrument']:<17} grades {', '.join(grade_order(p)):<26} confidence {p.get('confidence', '?'):<7} {p['system']}")


def main():
    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
    parser.add_argument('score', nargs='?')
    parser.add_argument('--instrument', default='piano', help='profile name (see --list)')
    parser.add_argument('--grade', default='1', help='grade key in the profile, e.g. 1')
    parser.add_argument('--part', type=int, default=1, help='part number to check for single-line instruments')
    parser.add_argument('--written-offset', type=int, help='semitones from concert to written pitch (overrides the profile; saxophone: soprano 2, alto 9, tenor 14, baritone 21)')
    parser.add_argument('--as-written', action='store_true', help='pitches are already written pitch (skip the concert-to-written shift)')
    parser.add_argument('--estimate', action='store_true', help='report the lowest grade with no check over')
    parser.add_argument('--json', action='store_true', help='print JSON instead of text')
    parser.add_argument('--mark', help='write a copy with notes that broke a check coloured red')
    parser.add_argument('--ignore', default='', help='comma-separated check names to report as info only, e.g. range,key (for an instrument that borrows another instrument\'s profile)')
    parser.add_argument('--list', action='store_true', help='list available profiles')
    args = parser.parse_args()
    if args.list:
        list_profiles()
        return
    if not args.score:
        parser.error('score file required')
    ignore = [x.strip() for x in args.ignore.split(',') if x.strip()]
    profile = load_profile(args.instrument)
    tree = load(args.score)
    notes, info = read_score(tree, profile['kind'], args.part)
    if not notes:
        sys.exit('No notes found: is this a MusicXML score?')
    shift_note = None
    offset = args.written_offset if args.written_offset is not None else profile.get('written_offset', 0)
    if offset and not info['has_transpose'] and not args.as_written:
        to_written(notes, info, offset)
        shift_note = (f'No transposition in the file, so the pitches are read as concert pitch and moved {"up" if offset > 0 else "down"} {abs(offset)} semitones '
                      f'to the written pitch this profile uses (--as-written turns this off)')
    if args.estimate:
        rows, lowest, likely = estimate(notes, info, profile, ignore)
        reliable = profile.get('reliable_up_to')
        out = {'instrument': profile['instrument'], 'lowest_grade_with_nothing_over': lowest, 'likely_grade': likely, 'grades': rows,
               'confidence': profile.get('confidence'), 'reliable_up_to': reliable}
        if args.json:
            print(json.dumps(out, ensure_ascii=False, indent=2))
            return
        print(f"{profile['instrument']} ({profile['system']}), confidence {profile.get('confidence', '?')}")
        if shift_note:
            print(f'({shift_note})')
        for r in rows:
            print(f"{r['label']:>10}: over {len(r['over'])}" + (f" ({', '.join(r['over'])})" if r['over'] else '') +
                  f", warn {len(r['warn'])}")
        print('\nLowest level with nothing over: ' + (grade_label(profile, lowest) if lowest else 'none, above the top of this profile'))
        print('Likely level (nothing over, at most two warnings): ' + (grade_label(profile, likely) if likely else 'none'))
        top = likely or lowest
        if reliable is not None and top is not None and int(top) > reliable:
            print(f'Note: above grade {reliable} this profile mostly leaves limits open, so read the result as "at least".')
        return
    key = grade_key(profile, args.grade)
    order = grade_order(profile)
    nxt = order[order.index(key) + 1] if order.index(key) + 1 < len(order) else None
    rep = run_checks(notes, info, profile, key, nxt, ignore)
    summary = {'instrument': profile['instrument'], 'system': profile['system'], 'grade': key,
               'confidence': profile.get('confidence'), 'verdict': verdict(profile, key, rep.results),
               'bars': info['bars'], 'checks': rep.results}
    if args.mark:
        for n in notes:
            if id(n.el) in rep.flagged:
                n.el.set('color', RED)
                for child in ('notehead', 'stem', 'beam', 'accidental'):
                    for c in n.el.findall(child):
                        c.set('color', RED)
        tree.write(args.mark, encoding='utf-8', xml_declaration=True)
    if args.json:
        print(json.dumps(summary, ensure_ascii=False, indent=2))
        return
    print(f"Profile: {profile['instrument']} ({profile['system']}), {grade_label(profile, key)}, confidence {profile.get('confidence', '?')}")
    if shift_note:
        print(f'({shift_note})')
    if profile['kind'] != 'keyboard' and info['parts'] > 1:
        print(f'(checked part {args.part} of {info["parts"]}; use --part to pick another)')
    for r in rep.results:
        print(f"{r['status']:>4}  {r['check']}: {r['detail']}")
    print(f"\nVerdict: {summary['verdict']}")


if __name__ == '__main__':
    main()
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 196kUpdated Claude CodeCodexVerifiedInstall