delmas41/gradusnotation

Поиск гармонических особенностей в реальном репертуаре: 482 проанализированных произведения (25+ общедоступных оркестровых частей Бетховена, Брамса, Брукнера, Дворжака, Чайковского, Малера, Холста, Равеля, Баха + 400+ хоралов Баха; 41 000 тактов). Запрос по типу каденции, классу хроматического аккорда, типу фактуры, ступени педали или тональности модуляции; получение ссылок на произведение / часть / такт. КОГДА ИСПОЛЬЗОВАТЬ: когда нужно привести пример из репертуара ПО ПАМЯТИ — выдуманные ссылки это аналог выдуманной гармонии. «Покажи фригийскую каденцию», «найди немецкую увеличенную сексту», «пассаж с доминантовой педалью», «часть с модуляцией в ми-бемоль мажор» — сначала ищи, потом цитируй полученные такты. КОГДА НЕ ИСПОЛЬЗОВАТЬ: для анализа партитуры, которая У ВАС есть (theory_analyze_score); для объяснений теории (knowledge_search). Учтите: это АВТОМАТИЧЕСКИЕ результаты анализа — точность опубликована на gradusmusic.com/harmony-benchmark; сверяйтесь с партитурой перед утверждениями. ВХОДНЫЕ ДАННЫЕ: хотя бы одно из { cadence: "PAC"|"IAC"|"HC"|"DC"|"Plagal"|"Phrygian", rn: хроматическое обозначение в ASCII ("V/V", "viio7/vi", "bII6", "Ger+6", "N6"), texture: "bare-fifth"|"unison"|"octaves"|"bare-third"|"dyad"|"silence", pedal: ступень ("1", "5", "b3"), key: "Eb major" }. Опционально: work (фильтр по одному произведению), limit (по умолчанию 20, максимум 100). ВЫХОДНЫЕ ДАННЫЕ (JSON): по каждому признаку { total, matches: [{ workId, title, movement, measure | measureStart+measureEnd }] } плюс сводка по корпусу и примечание о точности. ТИПИЧНАЯ ЗАДЕРЖКА: <300 мс (индексированный поиск — без сканирования всего корпуса на каждый запрос).

Проверяет партитуру MusicXML на соответствие The Gradus Engraving Rulebook. Выполняет более 30 статически проверяемых правил (арифметика тактов, группировка нот vs метр, лиги, разделение голосов, выбор добавочных линеек/ключей, знаки выразительности) и возвращает результаты, привязанные к партии и такту, каждый с указанием нарушенного опубликованного правила — код, URL и готовая к цитированию ссылка. ЗАЧЕМ ЭТО СУЩЕСТВУЕТ: ноты, сгенерированные LLM, как правило, плохо выгравированы — такты, которые не сходятся по сумме, лиги между разными высотами, группировки через тактовые черты — и нет другого публичного инструмента для проверки правил гравировки. Сгенерируйте, затем ПРОВЕРЬТЕ, затем исправьте; не доверяйте нотам, которые вы воспроизвели по памяти. КОГДА ИСПОЛЬЗОВАТЬ: после генерации или редактирования MusicXML, перед показом пользователю; когда пользователь спрашивает «правильно ли записана эта партитура»; перед подачей партитуры в гравировщик/рендерер; как этап верификации в любом цикле сочинения-записи. КОГДА НЕ ИСПОЛЬЗОВАТЬ: для музыкальной ОЦЕНКИ (гармония, качество контрапункта — используйте theory_analyze_score); для ошибок расположения/коллизий (они требуют просмотра отрендеренной страницы и выходят за рамки статического уровня); для ПОИСКА правила без партитуры на руках (используйте engraving_rules). ВХОД: ровно один из параметров: path (локальный .musicxml/.xml/.mxl файл — предпочтительно, сервер читает его, и партитура не попадает в ваш контекст), xml (строка MusicXML) или mxl_base64 (base64 .mxl). Сырой XML ограничен 2 МБ; .mxl — 2 МБ в сжатом виде / 100 МБ в распакованном. ВЫХОД (JSON): { coverage: {parts, voices, measures, notesRead, notesChecked, unchecked[]}, skippedRules[], findings: [{ruleId, severity, message, part, partName, measure, voiceIndex, where, rule?: {code, name, url, citation}}], summary: {errors, warnings, suggestions}, rulebook, attribution }. ЧИТАЙТЕ coverage.unchecked — всё, что проверщик не смог проверить, перечисляется там, а не молча пропускается; пустой список findings означает, что проверено только то, что действительно было проверено. Результат с measure: null означает, что местоположение не удалось определить точно, и об этом сообщается вместо предположения. ОТЧЁТНОСТЬ: передавайте результаты с…

Получает одно правило гравировки по его постоянному идентификатору, с предварительно отформатированной строкой цитирования и списком связанных правил. КОГДА ИСПОЛЬЗОВАТЬ: у вас уже есть идентификатор правила (из engraving_rules, из URL на Gradus или из предыдущего ответа), и вам нужен полный текст плюс готовая к цитированию ссылка; вы переходите по ссылке «связанные правила». КОГДА НЕ ИСПОЛЬЗОВАТЬ: вы не знаете идентификатор — сначала выполните поиск с помощью engraving_rules. Впрочем, угадать идентификатор можно: при промахе возвращаются близкие по значению идентификаторы, а не просто ошибка, так что вы сможете исправиться за один дополнительный вызов. ВХОДНЫЕ ДАННЫЕ: { id: string } — либо постоянный код цитирования («GE-036»), либо читаемый идентификатор правила («beam-never-crosses-authored-barline»). Оба варианта разрешаются, так что код, указанный в предыдущем ответе, можно запросить напрямую. ВЫХОДНЫЕ ДАННЫЕ (JSON): { rule: { code, id, name, convention, authority, houseCall?, consequence?, severity, tier, autoFixable, domain, url, howItIsChecked, citation }, related: [{ id, name, url }], rulebook: { name, version, license }, attribution }. Используйте строку citation дословно при цитировании правила. ПРИ ПРОМАХЕ: API возвращает HTTP 404 с { error: "rule_not_found", suggestions: [{ id, name, url }] }; этот инструмент выводит это тело в сообщении об ошибке, поэтому прочитайте подсказки и повторите попытку. ПРИМЕР ВХОДНЫХ ДАННЫХ: { "id": "beam-never-crosses-authored-barline" } ТИПИЧНАЯ ЗАДЕРЖКА: 30-200 мс. Кэшируется на CDN.

Ищет в The Gradus Engraving Rulebook — 423 правила нотной гравировки, каждое из которых формулирует правило, указывает трактат или спецификацию, на которую оно опирается (Gould's Behind Bars, Read's Music Notation, Ross's The Art of Music Engraving, Stone, SMuFL, MusicXML), и определяет, проверяемо ли правило только по партитуре или только по отрисованной странице. ПОЧЕМУ ЭТО СУЩЕСТВУЕТ: практика гравировки описана почти исключительно в защищённых авторским правом печатных изданиях без поискового индекса. Поэтому такие вопросы, как «может ли ребро пересекать тактовую черту», «в какую сторону идёт этот штиль» или «переносится ли этот знак альтерации через такт», не имеют цитируемого ответа в интернете. Полагаться на память ненадёжно. Лучше найти правило. КОГДА ИСПОЛЬЗОВАТЬ: перед созданием или исправлением нотной записи — чтобы проверить применяемое соглашение; когда пользователь спрашивает, как что-то записать или выгравировать; при проверке партитуры на ошибки гравировки; когда два источника расходятся и нужно понять, какой авторитет что говорит. КОГДА НЕ ИСПОЛЬЗОВАТЬ: для вопросов по ТЕОРИИ музыки (гармония, контрапункт, анализ) — используйте knowledge_search или theory_analyze_score; для проверки конкретной партитуры на соответствие правилам (этот инструмент возвращает правила, он не проверяет партитуру по ним); после кеширования (справочник версионирован и стабилен — получите и переиспользуйте). ВХОД: всё необязательно. q — поиск по подстроке в названиях и тексте правил (лучшая отправная точка). domain — одно из: accidentals, beaming, clefs-and-ledger-lines, expression-marks, horizontal-spacing, multiple-voices, rhythm-and-meter, score-conventions, stems-and-flags, text-and-lyrics, ties-and-slurs, vertical-spacing. severity — error | warning | suggestion. tier — static-model (проверяемо только по партитуре) | render-geometry (требует отрисованной страницы) | hybrid. fields — список полей через запятую, чтобы сократить полезную нагрузку. Если ничего не передано, возвращаются все 423 правила. ВЫХОД (JSON): { rulebook: { name, version, license, citationPolicy, publishedRules, withheldRules, domains }, count, rules: [{ id, name, convention, …

Получает одно упражнение по цифрованному басу по его постоянному идентификатору: образцовую реализацию, заранее отформатированную строку цитирования, перекрёстные ссылки голосоведения, раскрытые в именованные паттерны, и список соседних упражнений. КОГДА ИСПОЛЬЗОВАТЬ: у вас уже есть идентификатор упражнения (из figured_bass_exercises, URL Gradus или предыдущего ответа) и нужна полная запись — заданный бас, образцовая реализация, методическое пояснение о том, почему он движется именно так, и указания для клавира; вы ведёте ученика вперёд или назад по этапу через соседние упражнения. КОГДА НЕ ИСПОЛЬЗОВАТЬ: вы не знаете идентификатор — сначала поищите через figured_bass_exercises. Впрочем, можно и угадать: при промахе вернутся близкие по написанию идентификаторы, а не голая ошибка, так что поправитесь за один дополнительный вызов. ВХОД: { id: string } — постоянный идентификатор упражнения, например "bass-225". ВЫХОД (JSON): { exercise: { …все поля, которые возвращает поиск…, citation }, drills: [{ code, name, url }], neighbours: { prev?, next? }, corpus: { name, version, license }, attribution }. Поле solution объясняет, почему реализация движется именно так — цитируйте его, а не придумывайте своё объяснение. drills раскрывает GVL-коды упражнения в именованные паттерны голосоведения, так что можно сослаться на правило вместе с примером. Упражнения этапа 17 также содержат floridRealization — аккорды, развёрнутые в характерную фактуру. КАК ОБУЧАТЬ: дайте ученику givenBass и teaches; realization придержите до попытки, потом сравните. Реализация — это ОБРАЗЕЦ, а не единственный правильный ответ: другая реализация, не нарушающая правил, тоже верна, так что расхождение — это не ошибка. ПРИ ПРОМАХЕ: API возвращает HTTP 404 с { error: "exercise_not_found", suggestions: [{ id, title, url }] }; этот инструмент отображает это тело в сообщении об ошибке, так что читайте подсказки и пробуйте снова. ПРИМЕР ВХОДА: { "id": "bass-225" } ТИПИЧНАЯ ЗАДЕРЖКА: 30-200 мс. Кэшируется на CDN.

Ищет The Gradus Figured-Bass Corpus — 166 оригинальных градуированных упражнений на генерал-бас в семнадцати этапах, от трезвучий в основном виде до октавного правила, каденционных формул, задержаний, доминантсептаккорда, секвенций, особенностей минора, педального баса, схем Рипеля, модуляций, хроматики, нефигурированного баса и диминуций. Каждое упражнение содержит бас с цифровкой И четырехголосную модель реализации, проверенную машиной на голосоведение. ПОЧЕМУ ЭТО СУЩЕСТВУЕТ: градуированный генерал-бас — это то, как гармонии реально обучали два столетия, но сохранившиеся сборники либо не переиздаются, либо защищены авторским правом, и в них почти никогда не публикуют ответы — поэтому ученику не с чем сверяться, а преподавателю приходится придумывать упражнения по памяти, и получается плохо. Этот корпус — открытая замена: написан с нуля, разбит на этапы по сложности и опубликован ВМЕСТЕ с реализациями. КОГДА ИСПОЛЬЗОВАТЬ: когда пользователь хочет практиковать генерал-бас на конкретном уровне; когда нужно готовое упражнение на какой-то прием (задержание 4–3, каденционный квартсекстаккорд, нисходящую секвенцию) — показать, а не объяснять; когда студент уже сделал свой бас и хочет сравнить с эталонным решением; когда нужно выстроить последовательность упражнений и перейти к следующему шагу. КОГДА НЕ ИСПОЛЬЗОВАТЬ: чтобы узнать ПРАВИЛО, стоящее за приемом — для этого есть voice_leading_patterns, где правило сформулировано и указан источник (этот инструмент дает упражнения, а не теорию); чтобы проанализировать партитуру, которую принес пользователь — для этого есть theory_analyze_score; чтобы оценить видовой контрапункт — для этого есть counterpoint_check; для вопросов о том, как нотация должна ВЫГЛЯДЕТЬ на странице — для этого есть engraving_rules; после кэширования (корпус версионирован и стабилен). ВХОДНЫЕ ДАННЫЕ: все необязательно. stage принимает либо номер (1–17), либо постоянный слаг: root-position-triads, rule-of-the-octave, first-inversion, cadence-formulas, second-inversion, suspensions, dominant-seventh, sequences, minor-mode, bare-accidentals, non-dominant-sevenths, pedal-point, schemata, modulation,…

Выполняет поиск в базе знаний Gradus по теории музыки для получения авторитетных исходных материалов. Корпус включает авторские учебные тексты, анализ хоралов Баха (408 хоралов), комментарии к партитурам более чем 50 оркестровых произведений, а также первоисточники от Фукса (1725) до Буланже. КОГДА ИСПОЛЬЗОВАТЬ: перед генерацией нотной записи, если нужно уточнить конкретный теоретический факт — типовое голосоведение при разрешении неаполитанского аккорда в доминанту, idiomatic генерал-бас для определённой каденции, чем хроматическая медианта в стиле одного композитора отличается от другого. Обращение к этому инструменту в первую очередь предотвращает выдумывание агентом стилистически неверных аккордовых последовательностей. КОГДА НЕ ИСПОЛЬЗОВАТЬ: для общих музыкальных понятий («что такое аккорд?»), которые любой LLM уже знает; для запросов, не связанных с теорией, например биографий композиторов, рекомендаций по исполнению или исторических дат — они выходят за рамки; для получения собственно нотной записи (используйте вместо этого notation_render или notation_examples). ВХОДНЫЕ ДАННЫЕ: укажите ЛИБО topics (теги в kebab-case), ЛИБО step (шаг учебного плана, 1-49). topics предпочтительнее; step — запасной вариант, если вы не знаете канонический тег темы. Если оба пусты, возвращается ошибка MISSING_QUERY. ВЫХОДНЫЕ ДАННЫЕ (JSON): { ok: true, requestId, chunks: [{ id, sourceType, sourceId, title, content, composer?, era?, topics: string[], curriculumSteps: number[], tokenEstimate }], meta: { query, returnedCount, totalTokens, responseTimeMs }, attribution }. sourceType — одно из: kg_concept, score_analysis, score_commentary, bach_chorale_analysis, composer, dictionary, curriculum, lesson_content, practicum, voice_leading, fugue, chorale_exercise и т.д. Пустой chunks: [] означает, что по темам ничего не найдено — агенту следует опереться на собственные знания или попробовать другой тег. ПРИМЕР ВХОДНЫХ ДАННЫХ: { "topics": ["voice-leading", "deceptive-cadence"], "limit": 3 } ТИПИЧНАЯ ЗАДЕРЖКА: 200-700 мс (один вызов эмбеддинга Voyage 3 + RPC Supabase pgvector).

Оценивает музыкальное произведение по 32-мерной шкале Gradus craft scorecard — голосоведение (параллельные квинты/октавы, расстояния между голосами, пересечения), качество контрапункта, мелодический контур, обработка диссонансов, гармоническая логика, ритм, фактура и другое, с калибровкой под указанный стилистический период. Чисто программный инструмент (без LLM внутри): детерминированный, быстрый и бесплатный — движок оценки, лежащий в основе обратной связи, основанной на фактических данных. КОГДА ИСПОЛЬЗОВАТЬ: когда пользователь или студент делится произведением и спрашивает «это хорошо / что исправить» — сначала дайте критику и опирайтесь на возвращённые данные, а не на впечатления; при рецензировании упражнения, аранжировки или черновика, чтобы подкрепить конкретные похвалы и конкретные исправления; как проверку качества перед тем, как выставлять любую оценку. КОГДА НЕ ИСПОЛЬЗОВАТЬ: для гармонического АНАЛИЗА существующего репертуара (theory_analyze_score — тот называет аккорды и тональности; этот оценивает мастерство); для ошибок гравировки/нотации (engraving_check); для эстетических предпочтений за пределами ремесла (выбор темпа, эмоциональный регистр — это ваше суждение, а не инструмента). ВХОДНЫЕ ДАННЫЕ: ровно один из { path } (путь к файлу партитуры, предпочтительно — .mxl передаётся в сжатом виде), { xml } или { mxlBase64 }. Плюс stylePeriod? (modal | baroque | classical (по умолчанию) | romantic | impressionist | post_tonal | film_contemporary | jazz | minimalist — пороговые значения калибруются под стиль, так что укажите намеренный стиль), focusAreas? (string[]), context? (одно предложение о намерении). ВЫХОДНЫЕ ДАННЫЕ (JSON): { meta: { title, partNames, measureCount, noteCount, voiceCount, stylePeriod }, critique: { dimensions: [{ id, name, family, score: 1-5 | null, evidence }], strengths: top 3, growthAreas: bottom 3, scoredCount, naCount, average } }. score: null = не применимо (одноголосная мелодия не может быть «плохой по голосоведению»); null-измерения никогда не учитываются в среднем. ТИПИЧНАЯ ЗАДЕРЖКА: 300-800 мс.

Получает шесть канонических примеров входных данных, покрывающих наиболее распространённые сценарии использования notation_render: одноголосная мелодия, двухголосный контрапункт (cantus firmus + контрапункт), аккордовая последовательность (каденция), смешанные ритмы с динамикой и артикуляцией, струнный квартет из четырёх инструментов и ноты, связанные лигой через тактовую черту. КОГДА ИСПОЛЬЗОВАТЬ: при первом знакомстве с этим MCP — получает примеры для изучения формата входных данных на конкретных отработанных шаблонах; перед вызовом notation_render, если вы не уверены, как выразить определённую музыкальную структуру (аккорд, многоголосный нотоносец, связанную лигой ноту); чтобы показать конечному пользователю, какие виды нотации возможны. КОГДА НЕ ИСПОЛЬЗОВАТЬ: после кэширования ответа (примеры стабильны во всех версиях v1 API; получайте один раз и используйте повторно вечно); когда вам нужны только формальные определения типов (используйте notation_schema для JSON Schema). ВХОДНЫЕ ДАННЫЕ: нет. Передайте пустой объект {}. ВЫХОДНЫЕ ДАННЫЕ (JSON): { ok: true, examples: [{ id, title, description, use_when, input: NotationInput }], docs: { schema, render, validate }, attribution }. Шесть примеров со стабильными id: single-melody, two-voice-counterpoint, chord-progression, mixed-rhythms, string-quartet-snippet, tied-across-bar. Каждый input — это полная полезная нагрузка, которую можно передать напрямую в notation_render. ПРИМЕР ВХОДНЫХ ДАННЫХ: {} (без параметров) ТИПИЧНАЯ ЗАДЕРЖКА: 30–200 мс. Ответ кэшируется на CDN с длинным TTL - последующие вызовы практически бесплатны.

Преобразует нотную запись из JSON-оценки в три выходных формата за один вызов: встраиваемый SVG (гравировка через Verovio со шрифтом Bravura SMuFL — тот же движок, что у IMSLP и Music Encoding Initiative), MusicXML с круговой совместимостью (чисто открывается в Sibelius, Finale, MuseScore, Dorico) и MIDI в формате SMF Type-1, закодированный в base64. КОГДА ИСПОЛЬЗОВАТЬ: когда агенту нужно показать пользователю гравированную нотацию (композитору, демонстрирующему идею, учителю, создающему рабочий лист, создателю контента, встраивающему пример нотации), или при конвертации JSON-оценки в форматы файлов, которые могут читать другие агенты или инструменты (MusicXML для настольных нотных редакторов, MIDI для секвенсоров). КОГДА НЕ ИСПОЛЬЗОВАТЬ: если вы не уверены, что входные данные корректны → сначала вызовите notation_validate (гораздо дешевле, без отрисовки); если вы еще не знаете формат входных данных → вызовите notation_examples или notation_schema; если вам нужны теоретические факты перед сочинением → сначала вызовите knowledge_search. ВХОДНЫЕ ДАННЫЕ: требуется instruments (непустой массив). Каждый инструмент имеет name (обязательно; ключ выводится из названия: "Cello" → басовый, "Viola" → альтовый, "Timpani" → ударный — можно переопределить через clef) и либо notes (сокращение для одного голоса), либо voices (несколько голосов). Высоты нот задаются в научной нотации ("C4", "F#5", "Bb3"); длительности — буквенными кодами ("w", "h", "q", "8", "16", "32", "64" с необязательным "." для пунктирной, ".." для двойной пунктирной). Тактовые черты выводятся из timeSignature (по умолчанию [4,4]); ноты, пересекающие тактовую черту, автоматически разбиваются и связываются — агентам не нужно считать доли. ВЫХОДНЫЕ ДАННЫЕ (JSON, успех): { ok: true, requestId, outputs: { svg: string, musicxml: string, midiBase64: string }, meta: { measureCount, instrumentCount, voiceCount, durationBeats, renderTimeMs }, warnings?: ValidationIssue[], attribution }. ValidationIssue = { path, code, message, fix?, severity: "error"|"warning" }. Обычно SVG занимает 60-100 КБ со встроенным шрифтом Bravura; MusicXML — несколько КБ; MIDI — менее 1 КБ. ВЫХОДНЫЕ ДАННЫЕ (JSON, ошибка валидации): { ok: false, requestId, errors:… }

Получает JSON-схему (Draft 2020-12), описывающую входную структуру notation_render. Включает все поля, их типы, значения по умолчанию, правила валидации (включая регулярное выражение для shorthand-string) и $defs для Instrument, VoiceLine, Note и NoteObject. КОГДА ИСПОЛЬЗОВАТЬ: при первом знакомстве с этим MCP, когда нужны машиночитаемые определения типов; при создании клиента, который валидирует входные данные на стороне клиента перед вызовом notation_render; при генерации кода (типы TypeScript, схемы Zod и т.д.), который использует этот формат. КОГДА НЕ ИСПОЛЬЗОВАТЬ: после кэширования ответа (стабильный во всём v1 API); когда нужно обучение на примерах (используйте notation_examples — рабочие полезные нагрузки легче читать, чем определения схем). ВХОДНЫЕ ДАННЫЕ: нет. Передайте пустой объект {}. ВЫХОДНЫЕ ДАННЫЕ (JSON): { ok: true, schema: { $schema: "https://json-schema.org/draft/2020-12/schema", $id, title, type: "object", required: ["instruments"], properties, $defs: { Instrument, VoiceLine, Note, NoteObject } }, docs: { examples, render, validate }, attribution }. Поле schema — это полный документ JSON-схемы. ПРИМЕР ВХОДНЫХ ДАННЫХ: {} (без параметров) ТИПИЧНАЯ ЗАДЕРЖКА: 30-200 мс. Ответ кэшируется на CDN с большим TTL — последующие вызовы практически бесплатны.

Выполняет предварительную проверку ввода notation_render без рендеринга. Возвращает ошибки с конкретным полем fix, которое сообщает агенту, как именно исправить повреждённый ввод. Значительно дешевле, чем notation_render, поскольку полностью пропускает этап гравировки Verovio. КОГДА ИСПОЛЬЗОВАТЬ: когда повторяете форму ввода и не уверены, что она корректна; когда ввод получен от пользователя или от LLM и может быть повреждён; когда нужно показать точные ошибки валидации конечному пользователю до полноценного рендеринга; когда изучаете формат ввода (используйте вместе с notation_examples для просмотра канонических примеров). КОГДА НЕ ИСПОЛЬЗОВАТЬ: если ввод заведомо корректен (просто вызовите notation_render — он тоже проверяет внутри); если вы ещё не изучили схему (сначала вызовите notation_schema или notation_examples, чтобы увидеть формат). ВВОД: форма идентична notation_render. Массив instruments обязателен (каждый элемент содержит name и notes или voices). ВЫВОД (JSON, валидный): { ok: true, requestId, valid: true, warnings: ValidationIssue[], meta: { measureCount, instrumentCount, voiceCount, durationBeats }, attribution }. Warnings — неблокирующие уведомления (например, нестандартная обработка размера). ВЫВОД (JSON, невалидный): { ok: false, requestId, valid: false, errors: ValidationIssue[], warnings, attribution }. Каждый ValidationIssue: { path: "instruments[0].voices[0].notes[3]", code: "BAD_PITCH"|"BAD_DURATION"|"MISSING_FIELD"|"BAD_KEY_SIG"|..., message, fix: "Use scientific notation: letter A-G + optional # or b + octave number, e.g. C4, F#5, Bb3.", severity: "error"|"warning" }. Покажите fix пользователю или используйте его для автоматического исправления. ПРИМЕР ВВОДА: { "instruments": [{ "name": "Violin", "notes": ["C5/q","D5/q","E5/q","F5/q"] }] } ТИПИЧНАЯ ЗАДЕРЖКА: 30-100 мс (без рендеринга Verovio; чистое преобразование JSON в Score + расчёт тактовых линий).

Однократный эндпоинт: разбирает MusicXML, запускает полный конвейер гармонического анализа MaestroAnalyzer и запрашивает Knowledge Base Gradus (GKB) для проверенных теоретических блоков, сопоставленных с обнаруженными особенностями партитуры. Возвращает и алгоритмический анализ, и релевантные вручную составленные знания в одном вызове. КОГДА ИСПОЛЬЗОВАТЬ: когда у агента есть партитура MusicXML и он хочет узнать, что в ней гармонически примечательного — тональность, последовательность локальных тональностей, аккордовый анализ с римскими цифрами, каденции, фразовая структура, период стиля И релевантный теоретический контекст из GKB (правила голосоведения, гармонический словарь, оркестровые заметки, исторический контекст). Это самый насыщенный доступный анализ за один вызов. КОГДА НЕ ИСПОЛЬЗОВАТЬ: если вам нужна только проверка диапазонов (theory_validate_ranges); если нужна только перегармонизация (theory_respell); если нужен сырой поиск по GKB без анализа партитуры (knowledge_search). ВХОДНЫЕ ДАННЫЕ: ровно одно из { path } (локальный файл партитуры, ПРЕДПОЧТИТЕЛЬНО — .mxl или .musicxml; .mxl сжимается, чтобы поместились полные части), { xml } (сырой текст MusicXML, лимит 2 MB) или { mxlBase64 }. Плюс: maxKnowledgeTokens? (по умолчанию 1500), includeKnowledge? (по умолчанию true), measures? ([от, до] — ограничивает вывод потактовых данных нужными тактами), full? (по умолчанию false — по умолчанию ответ — это КОМПАКТНАЯ сводка: тональности, разделы с поддержкой, каденции, потактовые фактуры, одно прочтение на аккордовый срез с метками педального тона и тяготения. Полный понотный ответ части занимает мегабайты; передавайте full: true, только если нужны сырой повтор партитуры и прочтения). ВЫХОДНЫЕ ДАННЫЕ: { meta: { partCount, noteCount, measureCount }, analysis: { overallKey: { key, mode, confidence }, localKeys: [{ measure, key, confidence }], chordAnalyses: [{ measure, beat, primary, readings: [{ rn, rnAscii, inversion, localKey, confidence }], tendencyTones }], cadences: [{ type: "PAC"|"IAC"|"HC"|"DC"|"Plagal"|"Phrygian"|"unclear", ... }], phrases: [{ index, measureStart, measureEnd, fermataMeasures }], }, …

Преобразует строку MusicXML в объект Score библиотеки maestroAnalyst. Score — входной тип для theory_validate_ranges, его можно передать в любую аналитическую функцию maestroAnalyst. КОГДА ИСПОЛЬЗОВАТЬ: когда у вас есть MusicXML-файл (например, экспортированный из Sibelius, Finale, MuseScore, Dorico или созданный с помощью notation_render) и вы хотите его проанализировать — определить тональность, проверить диапазоны, переписать знаки альтерации. Это точка входа для нативного конвейера анализа, который заменяет music21. ОГРАНИЧЕНИЯ: принимает текст MusicXML в формате score-partwise. НЕ принимает ZIP-архивы .mxl — при необходимости распакуйте их. Score-timewise и другие не-partwise форматы не поддерживаются. ВХОДНЫЕ ДАННЫЕ: { xml: string } — полный текст документа MusicXML. ВЫХОДНЫЕ ДАННЫЕ: { ok, requestId, score: Score, meta: { partCount, noteCount, measureCount }, attribution }. Полученный JSON объекта Score затем можно передать в theory_validate_ranges или любой другой инструмент теории. ТИПИЧНЫЙ РАЗМЕР: хорал Баха (4 партии, 32 такта) создает Score примерно с 512 нотами. Часть симфонии Бетховена (12 партий, 400 тактов) может дать более 8 000 нот. Уложитесь в лимит контекста или обрабатывайте частями.

Набор быстрых чистых утилит для работы с высотой тона, заменяющих наиболее используемые функции music21 без сетевых задержек. ОПЕРАЦИИ: midi_to_pitch - MIDI-номер → строковое представление ноты. midi=60 → "C4". preferFlats=true → обозначения "Db". pitch_to_midi - строковое представление ноты → MIDI-номер. "C4"→60, "F#5"→78, "Bb3"→46. Возвращает null для пауз. interval_name - количество полутонов → строка качества интервала. 0→"P1" 3→"m3" 4→"M3" 7→"P5" 12→"P8". Составные интервалы: 14→"M2+8". transpose_pitch - сдвигает ноту на заданное количество полутонов. "C4"+7→"G4", "E5"+-2→"D5". preferFlats управляет обозначением чёрных клавиш. КОГДА ИСПОЛЬЗОВАТЬ: быстрая арифметика при генерации или анализе партитуры без запуска полного конвейера анализа; заполнение таблиц MIDI-вывода; маркировка интервалов в учебных целях; транспонирование отдельных нот во время сочинения. ВХОДНЫЕ ДАННЫЕ: { op: string, ...params }, где op — одна из указанных операций. ПРИМЕРЫ: { op: "midi_to_pitch", midi: 60 } → { pitch: "C4" } { op: "pitch_to_midi", pitch: "F#5" } → { midi: 78 } { op: "interval_name", semitones: 7 } → { interval: "P5" } { op: "transpose_pitch", pitch: "C4", semitones: 7 } → { pitch: "G4" } { op: "transpose_pitch", pitch: "E4", semitones: 1, preferFlats: true } → { pitch: "F4" }

Предлагает предпочтительное энгармоническое написание для одного или нескольких тонов в заданном тональном контексте. Выбирает написание, диатоническое для тональности (например, F# в G major, Gb в F major). Использует предпочтение знаков альтерации тональности (диезы/бемоли) как критерий разрешения для хроматических проходящих тонов. КОГДА ИСПОЛЬЗОВАТЬ: после OMR (оптического распознавания музыки) для исправления неправильно написанных знаков альтерации; при создании нотной записи, когда не уверены, написать F# или Gb; при транспонировании — переписать после полутонового сдвига для сохранения диатонического написания; перед вызовом notation_render для очистки знаков альтерации. ВХОДНЫЕ ДАННЫЕ: { keyContext: string, pitches: string[] } ИЛИ { keyContext: string, pitch: string }. Строки тонов используют научную нотацию: "F#4", "Bb3", "C5", "Eb4". ВЫХОДНЫЕ ДАННЫЕ: { ok, requestId, keyContext, results: [{ input, output, changed }], attribution }. changed принимает значение true, если написание было скорректировано. ПРИМЕРЫ: { keyContext: "F major", pitches: ["F#4", "Bb4", "E4"] } → F#4→Gb4 (Gb диатоничен для F major), Bb4 без изменений, E4 без изменений. { keyContext: "G major", pitch: "Gb4" } → Gb4→F#4 (F# диатоничен для G major).

Проверяет каждую ноту в Score JSON на соответствие стандартному практическому диапазону инструмента. Возвращает предупреждения о выходящих за диапазон высотах с указанием такта, доли, MIDI-номера и уровня серьезности. КОГДА ИСПОЛЬЗОВАТЬ: после разбора файла MusicXML с помощью theory_parse_xml и перед анализом — чтобы выявить неисполнимые или экстремальные ноты на раннем этапе; при программном создании или редактировании партитуры и необходимости проверить соответствие инструментальному диапазону; когда студент представляет сочинение для рецензии и нужно отметить ошибки диапазона. УРОВНИ СЕРЬЕЗНОСТИ: "error" — нота находится более чем на 1 полутон вне практического диапазона; "warn" — нота находится на границе (в пределах 1 полутона). ПОДДЕРЖИВАЕМЫЕ ИНСТРУМЕНТЫ (частичное совпадение имени, без учета регистра): Violin, Viola, Cello, Double Bass, Harp, Flute, Piccolo, Oboe, English Horn, Clarinet, Bass Clarinet, Bassoon, Contrabassoon, Soprano/Alto/Tenor/Baritone Sax, Horn, Trumpet, Trombone, Tuba, Piano, Organ, Marimba, Xylophone, Vibraphone, Glockenspiel, Timpani, Soprano/Mezzo/Alto/Tenor/Baritone/Bass (voice). ВХОДНЫЕ ДАННЫЕ: объект maestroAnalyst Score — получите его, вызвав theory_parse_xml с текстом MusicXML. ВЫХОДНЫЕ ДАННЫЕ: { ok, requestId, warnings: [{ measure, beat, pitch, midi, partId, instrumentName, min, max, severity }], attribution }. Пустой массив warnings означает, что все ноты в диапазоне. ПРИМЕР: передайте Score с партией скрипки, содержащей ноту A7 (MIDI 105) — он вернет уровень серьезности "error", поскольку диапазон скрипки заканчивается около B7/MIDI 107, но A7 выходит за пределы практического диапазона.

Получает один голосоведческий паттерн по его постоянному идентификатору, с заранее отформатированной строкой цитирования и списком связанных паттернов. КОГДА ИСПОЛЬЗОВАТЬ: у вас уже есть идентификатор паттерна или код GVL (из voice_leading_patterns, из URL Gradus или из предыдущего ответа), и вам нужна полная запись — утверждение, реализация, классические ошибки, общедоступные источники — плюс готовая к цитированию строка; вы переходите по ссылке «связанные паттерны». КОГДА НЕ ИСПОЛЬЗОВАТЬ: вы не знаете идентификатор — сначала поищите через voice_leading_patterns. Угадывать идентификатор можно: если промахнётесь, вернутся похожие идентификаторы, а не голая ошибка, так что исправитесь за один дополнительный вызов. ВХОДНЫЕ ДАННЫЕ: { id: string } — либо постоянный код цитирования («GVL-001»), либо читаемый идентификатор паттерна («suspension-4-3»). Оба варианта работают, так что код из предыдущего ответа можно подставлять напрямую. ВЫХОДНЫЕ ДАННЫЕ (JSON): { pattern: { code, id, name, family, statement, realization, whenToUse, commonFaults, sources, related, tags, url, citation }, related: [{ id, name, url }], reference: { name, version, license }, attribution }. При цитировании паттерна используйте строку citation дословно. ПРИ ПРОМАХЕ: API возвращает HTTP 404 с { error: "pattern_not_found", suggestions: [{ id, name, url }] }; этот инструмент показывает тело ошибки в сообщении, так что читайте подсказки и пробуйте снова. ПРИМЕР ВВОДА: { "id": "suspension-4-3" } ТИПИЧНАЯ ЗАДЕРЖКА: 30–200 мс. Кешируется на CDN.

Поиск по справочнику голосоведения Gradus — цитируемые образцы голосоведения и генерал-баса по шести категориям (нормы голосоведения, видовые контрапункты, задержания и обработка диссонансов, каденции, правило октавы, секвенции и басовые движения). Каждый образец формулирует правило, показывает его реализацию в голосах, составленную для справочника, перечисляет типичные ошибки и ссылается на общедоступный трактат, на который опирается (Фукс, Рамо, Кирнбергер, К. Ф. Э. Бах, Фенароли, Кампион, Рипель, Керубини, Проут, Риман), с указанием главы или раздела. ЗАЧЕМ ЭТО НУЖНО: искусство голосоведения было систематизировано столетия назад, а затем разбросано по недоступным трактатам без поискового указателя — поэтому вопросы вроде «как должно разрешаться задержание 4–3», «когда допустимо параллельное движение к октаве» или «какой аккорд берётся над четвёртой ступенью» получают ответы по памяти, ненадёжно. Найдите образец и сошлитесь на него. КОГДА ИСПОЛЬЗОВАТЬ: когда пользователь или студент показывает голосоведение, а вы хотите обосновать свой отзыв цитируемым правилом, а не пересказом; когда пользователь спрашивает, как работают задержание, каденция, секвенция или гармонизация гаммы; перед тем как писать или исправлять голоса, чтобы свериться с нормой, которую собираетесь применить; когда нужно объяснить, какие типичные ошибки допущены в отрывке. КОГДА НЕ ИСПОЛЬЗОВАТЬ: для вопросов о том, как нотация должна ВЫГЛЯДЕТЬ на странице (используйте engraving_rules); для анализа конкретной партитуры (используйте theory_analyze_score — этот инструмент возвращает справочную ссылку, он не читает партитуры); для автоматической проверки видового контрапункта (используйте counterpoint_check); для поиска примеров из репертуара (используйте corpus_search); после кэширования (справочник версионирован). ВХОДНЫЕ ДАННЫЕ: все параметры необязательны. q — подстрока для поиска по названию, описанию, формулировке и тегам (лучшая отправная точка). family — одна из категорий: part-writing, species, suspensions, cadences, rule-of-the-octave, bass-motions. fields — список полей через запятую, чтобы сократить вывод. Если ничего не передано, возвращаются все образцы. ВЫХОДНЫЕ ДАННЫЕ (JSON): { reference: { name,…