Developer changelog

Панель разработчика перестроена вокруг возможностей вашей интеграции. Для каждой возможности (Embed, OMR, REST API, Import API, LTI) теперь есть карточка с областью действия, ценами и документацией, а те, которые ваше приложение уже использует, показываются первыми.

• Новый раздел OMR на уровне аккаунта: ваши задания, ваши кредиты и их история собраны в одном месте, поскольку кредиты OMR общие для всех ваших приложений.
• Попробуйте OMR до того, как писать код. Playground принимает PDF или фотографии, показывает число страниц, стоимость за страницу и остаток баланса после выполнения, а затем запускает задание после вашего подтверждения. Результат доступен для скачивания в MusicXML, в вашу библиотеку ничего не добавляется.
• Более понятные страницы приложений. Персональные токены, учетные данные OAuth2 и доступ к OMR сгруппированы по приложениям, а учетные данные с областью OMR выделены отдельно.

Откройте ее на странице flat.io/developers.

Наша спецификация REST API переходит на OpenAPI 3.1, API OMR завершает бета-период, а задания в Flat for Education теперь поддерживают не только просмотр списка и создание.

• API OMR стал стабильным. Эндпоинты, поля и поведение теперь следуют нашему обычному процессу устаревания перед любым ломающим изменением. В новом FAQ описаны кредиты и биллинг, лимиты и время обработки, качество распознавания и языки, а также коммерческое использование и конфиденциальность.
• Чтение, обновление и удаление заданий в Flat for Education. При удалении задания также удаляются его работы и копии у учеников; если нужно сохранить их, вместо этого архивируйте задание.
• Журнал кредитов. Новый вызов выводит историю ваших кредитов; баланс по-прежнему доступен через вызов возможностей OMR.
• Файлы Finale (.musx) теперь можно импортировать на условиях best-effort, а импорт сканированной музыки (PDF и изображения) документирован при создании партитуры.
• OpenAPI 3.1. Поля с nullable используют синтаксис 3.1; инструментам, привязанным к OpenAPI 3.0, требуется обновление. Поле mimeType было удалено из загрузки файлов OMR.

• Управляемое вами хранение данных. Задания OMR теперь сообщают, как долго хранятся их файлы (по умолчанию 30 дней), каждое задание MusicXML содержит дату истечения срока хранения, а файлы и результаты задания можно удалить сразу после того, как вы их получите.
• Определение возможностей до входа в систему. Вызов возможностей OMR теперь работает без учётной записи и возвращает список поддерживаемых языков распознавания с их названиями.
• Экспорт нотации ABC для любой редакции партитуры наряду с MusicXML, MIDI и другими форматами. Как и MIDI, он не сохраняет всё оформление нотной записи.
• Задания Free Record в Flat for Education теперь можно настраивать через API.
• Ошибки, приходящие от внешнего провайдера (например, Google Classroom), теперь содержат собственное локализованное сообщение этого провайдера.

Модуль OMR от Flat теперь доступен программно через API для разработчиков. Отправляйте PDF-файлы или фотографии, отслеживайте ход распознавания, проверяйте обнаруженные инструменты, а затем импортируйте результат как редактируемую партитуру в библиотеку Flat или экспортируйте в MusicXML или MIDI. Это та же внутренняя модель, которая лежит в основе импорта PDF и фотографий в редакторе, а теперь она доступна в масштабе для ваших собственных приложений и рабочих процессов.

Специализированный OMR API (v2.24.0) основан на фоновом импорте PDF, добавленном при создании партитуры в v2.23.0: запрашивайте поддержку задач при импорте файла и опрашивайте задачу, пока партитура не будет готова. Подробности по обоим выпускам смотрите в журнале изменений API.

Самое крупное обновление спецификации с 2024 года: API приведён в соответствие с изменениями продукта за последние два года.

• Импорт из 15+ форматов. Guitar Pro, MuseScore, ABC notation, PowerTab, Capella, MEI, Overture, TablEdit, Band-in-a-Box, Karaoke MIDI, MuseData, Score Writer, Bagpipe Music Writer и Encore присоединяются к MusicXML и MIDI, а партитуры можно экспортировать как собственные файлы .flat.
• Виртуальные коллекции. All scores, collaborations и likes заменяют устаревшую иерархию папок в библиотеке, в соответствии с переработанной библиотекой Flat.
• Flat for Education. Задания на исполнение с аудио- или видеозаписями и параметрами backing track, metronome и speed; групповые сдачи для совместного письма; инструкции с форматированным текстом; подгруппы учеников; задания Microsoft Teams с расписанием и индивидуальным назначением; подробные описания и типы заданий в библиотеке ресурсов.
• Единая конфигурация LTI для LTI 1.1 и 1.3, включая динамическую регистрацию. Предыдущие вызовы учётных данных LTI 1.1 объявлены устаревшими.
• Годовая статистика по партитурам, число публичных партитур в профилях и удаление нескольких давно устаревших полей.

• Добавлены методы getMP3 и getWAV для экспорта аудио
• Добавлено событие exportProgress, чтобы при длительном экспорте можно было показывать прогресс

• Списки партитур пользователей стали публичными профилями. Теперь при получении списка партитур пользователя возвращаются только его публичные партитуры; добавлены новые параметры пагинации и сортировки, как было объявлено в 2020 году.
• В сведениях о партитуре теперь доступны URL редактирования, названия инструментов и запланированная дата удаления; коллекции сообщают количество партитур; в публичных профилях отображается число отметок «Нравится» и прослушиваний.
• Flat for Education. Библиотеку ресурсов можно фильтровать по типу задания, предмету и классу; у ресурсов есть описание доступа и параметры конфиденциальности; в заданиях можно ограничивать воспроизведение нот и аудиодорожки; в ответах поддерживаются сервисы оценок LTI 1.1 и 1.3.

• Лайки в профилях пользователей теперь выводятся постранично, а в сведениях об аккаунте пользователя указывается, каким продуктом он пользуется.
• Права доступа к ресурсам теперь показывают, является ли вызывающий пользователь владельцем, соавтором-пользователем или соавтором-группой, а также дату добавления каждого соавтора. В сведениях о партитуре теперь указываются основная тональность, дата выделения и организация.
• Flat for Education. Приглашения теперь можно использовать несколько раз; у работ появился статус оценивания, а также сведения о воспроизведении и LTI; задание можно скопировать в библиотеку ресурсов только если его там ещё нет; организации получили собственные библиотеки ресурсов с уровнем конфиденциальности для всей организации.

Считывайте структуру загруженной партитуры из своего кода.

• Партии и голоса: getNbParts, getPartsUuids, getMeasureVoicesUuids
• Ноты: getMeasureNbNotes, getNoteData, playbackPositionToNoteIdx
• Новый URL-параметр noAudio отключает воспроизведение звука
• Исправлена ошибка, из-за которой setMasterVolume вызывал неправильный внутренний метод

• Удалена поддержка jQuery в конструкторе — вместо этого передавайте DOM-элемент или его id
• Опубликованный модуль npm включает типы TypeScript
• Отдельные сборки ES и UMD

• Создавайте LTI-ссылки из элементов библиотеки ресурсов Flat for Education, чтобы напрямую размещать их в курсе LMS.
• Максимальная оценка для задания увеличена со 100 до 10,000 баллов.
• Метаданные партитуры (подзаголовок, композитор, автор текста, аранжировщик, описание, лицензия и т. д.) теперь можно не только задавать, но и очищать через API.

• API библиотеки ресурсов (бета). Просматривайте библиотеки ресурсов Flat for Education и управляйте ими с помощью двух новых областей OAuth2 для полного доступа и доступа только на чтение. Задания можно копировать в библиотеку ресурсов.
• Тестовые учащиеся. Создавайте в классе тестовые учётные записи учащихся, чтобы проверить задания так, как их видит ученик.
• Задания сообщают, что с ними можно делать (редактировать, публиковать, архивировать…), являются ли их вложения отдельными копиями, а также о любых возникших проблемах. История отправки фиксирует источник изменения, если оно поступило из Google Classroom, Microsoft Teams или LMS.
• При сбросе отправка остаётся на месте вместо удаления; стали доступны метаданные класса (уровень, навыки, размер) и данные входа через Microsoft в учётных записях.
• Для редакций партитуры теперь возвращаются даты начала и окончания; конструкторы партитур могут включать четвертитоны; копии могут сохранять исходное название.

• Такты: getNbMeasures, getMeasuresUuids
• Навигация: goLeft, goRight, scrollToCursor
• Метроном: getMetronomeMode, setMetronomeMode
• Скорость воспроизведения: getPlaybackSpeed, setPlaybackSpeed

• Ссылки для входа и делегированные токены доступа. Администраторы Flat for Education могут создать ссылку для входа для любого пользователя своей организации или токен доступа, действующий от имени этого пользователя: это основа для пользовательских порталов и интеграций единого входа.
• Японский в хирагане (ja-HIRA) добавлен в список поддерживаемых языков; в публичных комментариях теперь отображается их статус модерации.
• При экспорте аудио набор MP3 возвращается как дорожка по умолчанию, если он существует. Возможность запрашивать только кэшированные экспорты удалена, поскольку теперь аудиоэкспорты всегда отдаются из кэша.

• Конструктор партитур. Создавайте пустую партитуру без импорта файла MusicXML: укажите список инструментов и, при необходимости, размер, тональность, табулатуру, сетки аккордов и макет страницы.
• Flat for Education. Пользователей организации теперь можно создавать с ролью; в рабочих листах можно перемешивать упражнения; в списке работ студентов отображаются входящие в них упражнения.

• Дорожки воспроизведения. Получайте список дорожек, которые Flat автоматически создаёт и синхронизирует (воспроизведение в формате MP3), точки синхронизации последнего файла воспроизведения и URL CDN экспортированного файла в теле ответа.
• Flat for Education. Преподаватели могут сбросить отправленную работу ученика; классы сообщают об учётных записях, которые не удалось добавить во время синхронизации; задания и отправленные работы показывают своё состояние в Microsoft Teams и связанные ссылки; копии заданий можно запланировать; отправленные работы с исполнением содержат сохранённую аудиодорожку.
• У профилей появилась обложка, а id текущего пользователя теперь можно запрашивать отдельно.

• loadFlatScore принимает sharingKey, поэтому можно загружать партитуру, к которой открыт приватный доступ по ссылке
• Добавлены setTrack, useTrack и seekTrackTo для динамической настройки аудиодорожки

• Экспорт оценок. Скачивайте оценки задания в файле CSV или Excel.
• У заданий есть свой тип и изображение обложки; при копировании задания можно перезаписать существующий черновик содержимым другого задания.
• Для соавторов отображается, остаются ли они в статусе ожидающего приглашения.

• Оценивание через API. Устанавливайте черновые и итоговые оценки, возвращайте сдачу ученику и получайте вычисляемые счётчики комментариев; максимальное количество баллов сохраняется вместе с оценкой.
• Комментарии к сдачам. Создавайте, просматривайте, обновляйте и удаляйте комментарии к сдаче.
• Параметры заданий. Наборы инструментов, ограничение воспроизведения, максимальное количество баллов, темы Google Classroom, назначение задания отдельным ученикам, заблокированные шаблоны, а также сведения о заданиях LTI, Canvas и MusicFirst.
• Администраторы могут редактировать имя пользователя, имя и адрес электронной почты управляемой учётной записи; списки пользователей можно фильтровать по наличию активной лицензии.
• Старые параметры сдачи studentComment и returnFeedback удалены в пользу новых вызовов для оценивания.

• Архивируйте и восстанавливайте задания из архива, а также получайте основной тип задания (новая партитура, шаблон или совместная работа).
• Пользователи организации. Создавайте учётные записи с именем и фамилией, сортируйте и фильтруйте списки пользователей, подсчитывайте пользователей, соответствующих фильтру, и фильтруйте участников групп по источнику синхронизации (Google Classroom, Microsoft Teams, Clever).
• В сведениях о партитуре теперь перечисляются аудиосэмплы, используемые при воспроизведении, а список инструментов нормализован и больше не зависит от сэмплов.

Управляйте миксом из своего кода и получайте данные о том, что находится под курсором.

• Громкость и отключение звука: getMasterVolume, setMasterVolume, getPartVolume, setPartVolume, mutePart, unmutePart
• Соло и реверберация: setPartSoloMode, unsetPartSoloMode, getPartSoloMode, getPartReverb, setPartReverb
• Просмотр сведений: getMeasureDetails, getNoteDetails
• Добавлены события: noteDetails, measureDetails, cursorContext

• Спецификация переходит на OpenAPI 3.0. Предыдущие версии были описаны в OpenAPI 2 (Swagger).
• Для партитур теперь доступны данные об аранжировщике и статистика прослушиваний; удаление можно запланировать на ближайшее время, а не оставлять объект в корзине.
• Flat for Education. Вложения к заданиям могут быть файлами Google Drive, классы содержат сведения о Microsoft Teams, а для образовательных аккаунтов доступны имя и фамилия.

• Изменения метаданных сразу появляются в редакторе. При обновлении через API названия партитуры, подзаголовка, композитора, автора слов или текста лицензии изменения в реальном времени передаются в открытые редакторы, и сохраняется новая версия. Описания теперь могут быть вдвое длиннее (2,000 characters).
• У сдач в Flat for Education теперь доступно их состояние (создано, сдано, возвращено); метаданные редакций возвращают последнее событие изменения.
• В список поддерживаемых языков добавлен турецкий; в публичных профилях теперь указано, принадлежит ли аккаунт команде Flat.

• Добавлен getMIDI
• getMusicXML теперь возвращает Uint8Array на верхнем уровне — ответ больше не содержит свойства .data
• voiceIdx курсора теперь называется voiceIdxInStaff

Обновлено для релиза embed.

• SDK теперь по умолчанию загружается с flat-embed.com
• Удалены устаревшее действие edit и событие edit
• Удалён setNoteColor

• Больше форматов импорта. Теперь можно импортировать файлы Guitar Pro (GP3, GP4, GP5, GPX, GP), PowerTab, TuxGuitar и MuseScore, а при импорте можно передавать имя файла.
• Коллекции можно выводить в списке внутри родительской коллекции, и для них указывается дата создания; у партитур перечисляются коллекции, в которые они входят.
• Контекстные комментарии привязываются к нотоносцу по идентификатору, а не по индексу, а права доступа к ресурсу показывают, является ли вызывающая сторона соавтором.

• API коллекций. Создавайте, просматривайте, обновляйте, удаляйте и восстанавливайте коллекции, просматривайте их партитуры, а также добавляйте и удаляйте партитуры, с тремя новыми областями OAuth2 для доступа только на чтение, только на добавление и полного доступа.
• Партитуры можно восстанавливать из корзины; удаление партитуры без прав администратора вместо этого отменяет общий доступ к ней для вашей учётной записи; копию можно направить в определённую коллекцию.
• Комментарии теперь можно фильтровать по типу (документные или встроенные).
• При экспорте партий теперь используются идентификаторы партий вместо индексов, а с сентября 2019 года список партитур пользователя возвращает только публичные партитуры.

• Управление аккаунтами организаций. Администраторы могут обновлять управляемые аккаунты, удалять их или переводить их в обычные пользовательские аккаунты; в списках пользователей и приглашений используется пагинация на основе курсора.
• У классов появляется неактивный статус, который можно снова сделать активным, а также указание домена Canvas LMS и секции Clever; у заданий появляется статус черновика и тип вложения «упражнение».
• В профилях теперь доступны тема оформления и сведения об используемых инструментах.

• Добавлен метод focusScore, чтобы передавать клавиатурный фокус партитуре
• Новое свойство defaultMode в конфигурации редактора

• Первые API для образования стали общедоступными. Управляйте классами, заданиями и сдачами работ, аккаунтами организаций и приглашениями, учётными данными LTI, а также группами и пользователями организации — всем, что нужно для интеграции в школе.
• Разграниченный доступ. Новые области OAuth2 охватывают классы, задания и администрирование организации, причём для каждой есть вариант только для чтения, поэтому интеграция запрашивает только действительно необходимый доступ.

Теперь ваш код может проверять конфигурацию встраивания и переключать его в режим редактора.

• Добавлены методы: getEmbedConfig, setEditorConfig, edit
• Добавлено событие: edit

SDK научился загружать партитуры из MusicXML и сообщать о том, что делает средство просмотра.

• Добавлены методы: getAutoZoom, setAutoZoom, loadMusicXML, getMusicXML
• Добавлены события: scoreLoaded, cursorPosition, rangeSelection, pause, stop, fullscreen, print
• Добавлены интеграционные тесты

Первый публичный релиз REST API Flat. Читайте данные своей учётной записи и управляйте ими, партитурами, пользователями и группами из собственных приложений и скриптов, используя OAuth2, чтобы действовать от имени других пользователей Flat.

Все последующие изменения записаны в журнале изменений API, а в документации для разработчиков описаны аутентификация, справочник API и руководства.