Developer changelog

Das Entwickler-Dashboard wurde rund um die Möglichkeiten deiner Integration neu aufgebaut. Jede Funktion (Embed, OMR, REST API, Import API, LTI) erhält eine Karte mit Umfang, Preisen und Dokumentation, und die Funktionen, die deine App bereits nutzt, stehen an erster Stelle.

• Ein neuer OMR-Bereich auf Kontoebene mit deinen Jobs, deinen Credits und ihrem Verlauf an einem Ort, da OMR-Credits von all deinen Apps gemeinsam genutzt werden.
• Probiere OMR aus, bevor du Code schreibst. Der Playground nimmt eine PDF oder Fotos, zeigt die Seitenzahl, die Kosten pro Seite und das verbleibende Guthaben an und startet den Job nach deiner Bestätigung. Die Ausgabe geht in MusicXML-Downloads, nichts landet in deiner Bibliothek.
• Klarere App-Seiten. Persönliche Tokens, OAuth2-Zugangsdaten und OMR-Zugriff sind pro Anwendung gruppiert; die Zugangsdaten mit OMR-Umfang sind dabei klar gekennzeichnet.

Du findest es unter flat.io/developers.

Unsere REST-API-Spezifikation wechselt zu OpenAPI 3.1, die OMR-API beendet ihre Beta-Phase, und Aufgaben in Flat for Education gehen über das bloße Auflisten und Erstellen hinaus.

• Die OMR-API ist stabil. Endpunkte, Felder und Verhalten folgen nun vor jeder inkompatiblen Änderung unserem üblichen Abkündigungsprozess. Eine neue FAQ behandelt Credits und Abrechnung, Limits und Verarbeitungszeiten, Erkennungsqualität und Sprachen sowie kommerzielle Nutzung und Datenschutz.
• Aufgaben lesen, aktualisieren und löschen in Flat for Education. Beim Löschen einer Aufgabe werden auch ihre Abgaben und die Kopien der Schülerinnen und Schüler entfernt; archiviere sie stattdessen, um die Arbeit zu behalten.
• Credit ledger. Ein neuer Aufruf listet deinen Credit-Verlauf auf; das Guthaben bleibt im Aufruf für die OMR-Funktionen.
• Finale-Dateien (.musx) können importiert werden, nach bestem Bemühen, und der Import gescannter Musik (PDF und Bilder) ist bei der Erstellung von Partituren dokumentiert.
• OpenAPI 3.1. Nullable-Felder verwenden die 3.1-Syntax; Werkzeuge, die auf OpenAPI 3.0 festgelegt sind, müssen aktualisiert werden. Das Feld mimeType wurde aus OMR-Datei-Uploads entfernt.

• Datenaufbewahrung unter Ihrer Kontrolle. OMR-Jobs geben jetzt an, wie lange ihre Dateien aufbewahrt werden (standardmäßig 30 Tage), jeder MusicXML-Job hat ein Ablaufdatum, und Sie können die Dateien und Ergebnisse eines Jobs löschen, sobald Sie sie abgeholt haben.
• Funktionsprüfung vor der Anmeldung. Der OMR-Funktionsaufruf funktioniert jetzt ohne Konto und listet die unterstützten Erkennungssprachen mit ihren Namen auf.
• ABC-Notation-Export für jede Partiturrevision, zusammen mit MusicXML, MIDI und den anderen Formaten. Wie bei MIDI wird dabei nicht die vollständige grafische Gestaltung übertragen.
• Free Record-Aufgaben können in Flat for Education über die API konfiguriert werden.
• Fehler von einem Upstream-Anbieter (zum Beispiel Google Classroom) enthalten jetzt die eigene lokalisierte Meldung des Anbieters.

Die OMR-Engine von Flat ist jetzt programmatisch über die Developer API verfügbar. Sende PDFs oder Fotos, verfolge den Erkennungsfortschritt, prüfe die erkannten Instrumente und importiere das Ergebnis dann als bearbeitbare Partitur in eine Flat-Bibliothek oder exportiere MusicXML oder MIDI. Es ist dasselbe hauseigene Modell, das den PDF- und Fotoimport im Editor ermöglicht, und steht jetzt in großem Maßstab für deine eigenen Apps und Workflows zur Verfügung.

Die dedizierte OMR-API (v2.24.0) baut auf dem Hintergrundimport von PDFs auf, der in v2.23.0 zur Partiturerstellung hinzugefügt wurde: Fordere beim Importieren einer Datei Aufgabenunterstützung an und frage die Aufgabe ab, bis die Partitur bereit ist. Details zu beiden Releases findest du im API-Änderungsprotokoll.

Das größte Spezifikationsupdate seit 2024, das die API an zwei Jahre Produktänderungen anpasst.

• Import aus mehr als 15 Formaten. Guitar Pro, MuseScore, ABC-Notation, PowerTab, Capella, MEI, Overture, TablEdit, Band-in-a-Box, Karaoke MIDI, MuseData, Score Writer, Bagpipe Music Writer und Encore ergänzen MusicXML und MIDI, und Partituren können als native .flat-Dateien exportiert werden.
• Virtuelle Sammlungen. Alle Partituren, Kollaborationen und „Gefällt mir“-Angaben ersetzen die bisherige Ordnerhierarchie in der Bibliothek und entsprechen damit der neu gestalteten Flat-Bibliothek.
• Flat for Education. Performance-Aufgaben mit Audio- oder Videoaufnahmen sowie Optionen für Backingtrack, Metronom und Tempo; Gruppeneinreichungen für gemeinsames Schreiben; Anweisungen mit Rich-Text; Schüleruntergruppen; geplante und individuell zugewiesene Microsoft Teams-Aufgaben; ausführliche Beschreibungen und Aufgabentypen in der Ressourcenbibliothek.
• Einheitliche LTI-Konfiguration für LTI 1.1 und 1.3, einschließlich dynamischer Registrierung. Die bisherigen Anmeldedaten-Aufrufe für LTI 1.1 sind veraltet.
• Jährliche Statistiken zu Partituren, Anzahl öffentlicher Partituren auf Profilen und die Entfernung einiger seit Langem veralteter Felder.

• Die Methoden getMP3 und getWAV für den Audioexport wurden hinzugefügt
• Das Ereignis exportProgress wurde hinzugefügt, damit ein längerer Export den Fortschritt anzeigen kann

• Notenlisten von Nutzer:innen sind öffentliche Profile. Beim Auflisten der Partituren einer Person werden jetzt nur noch deren öffentliche Partituren zurückgegeben, mit neuer Paginierung und Sortierung, wie die 2020 angekündigte Änderung vorsah.
• Partiturdetails geben die Bearbeitungs-URL, Instrumentennamen und ein gegebenenfalls geplantes Löschdatum aus; Sammlungen melden die Anzahl ihrer Partituren; öffentliche Profile zeigen die Anzahl von Likes und Wiedergaben.
• Flat for Education. Filtern Sie die Ressourcenbibliothek nach Aufgabentyp, Fach und Klassenstufe; Ressourcen enthalten eine Freigabebeschreibung und Datenschutzoptionen; Aufgaben können die Notenwiedergabe und Audiospuren einschränken; Abgaben unterstützen die Benotungsdienste von LTI 1.1 und 1.3.

• Paginierte Likes auf Benutzerprofilen sowie das Produkt, das ein Benutzer in seinen Kontodaten verwendet.
• Ressourcenrechte geben an, ob der Aufrufer der Eigentümer, ein Benutzer-Mitarbeiter oder ein Gruppen-Mitarbeiter ist, einschließlich des Datums, an dem jeder Mitarbeiter hinzugefügt wurde. Notendetails enthalten jetzt die Haupttonart, das Hervorhebungsdatum und die Organisation.
• Flat for Education. Einladungen können mehrfach wiederverwendet werden; Abgaben erhalten einen bewerteten Status sowie Wiedergabe- und LTI-Details; eine Aufgabe kann nur dann in die Ressourcenbibliothek kopiert werden, wenn sie dort noch nicht vorhanden ist; Organisationen erhalten eigene Ressourcenbibliotheken mit einer organisationsweiten Datenschutzstufe.

Lies die Struktur der geladenen Partitur aus deinem Code aus.

• Stimmen und Voices: getNbParts, getPartsUuids, getMeasureVoicesUuids
• Noten: getMeasureNbNotes, getNoteData, playbackPositionToNoteIdx
• Der neue URL-Parameter noAudio deaktiviert die Audiowiedergabe
• Fehler behoben: setMasterVolume rief die falsche zugrunde liegende Methode auf

• Die Unterstützung für jQuery im Konstruktor wurde entfernt — übergeben Sie stattdessen ein DOM-Element oder dessen ID
• Das veröffentlichte npm-Modul enthält TypeScript-Typen
• Separate ES- und UMD-Builds

• LTI-Links erstellen aus Elementen der Flat for Education-Ressourcenbibliothek, um sie direkt in einem LMS-Kurs zu platzieren.
• Die maximale Punktzahl einer Aufgabe steigt von 100 auf 10.000 Punkte.
• Partitur-Metadaten (Untertitel, Komponist, Texter, Arrangeur, Beschreibung, Lizenz …) können jetzt über die API auch gelöscht und nicht nur gesetzt werden.

• Resource Library API (Beta). Durchsuche und verwalte Ressourcenbibliotheken in Flat for Education mit zwei neuen OAuth2-Scopes für Vollzugriff und Nur-Lesezugriff. Aufgaben können in die Ressourcenbibliothek kopiert werden.
• Testschüler. Erstelle Test-Schülerkonten in einer Klasse, um Aufgaben so auszuprobieren, wie es ein Schüler tun würde.
• Aufgaben geben an, was du mit ihnen tun kannst (bearbeiten, veröffentlichen, archivieren …), ob ihre Anhänge dedizierte Kopien sind und welche Probleme gegebenenfalls aufgetreten sind. Der Abgabeverlauf zeichnet die Quelle einer Änderung auf, wenn sie von Google Classroom, Microsoft Teams oder einem LMS kommt.
• Beim Zurücksetzen einer Abgabe bleibt diese erhalten, statt gelöscht zu werden; Klassenmetadaten (Niveau, Kompetenzen, Größe) und Microsoft-Anmeldedaten von Konten werden offengelegt.
• Partiturrevisionen geben ihr Start- und Enddatum zurück; Partitur-Builder können Vierteltöne aktivieren; Kopien können den ursprünglichen Titel beibehalten.

• Takte: getNbMeasures, getMeasuresUuids
• Navigation: goLeft, goRight, scrollToCursor
• Metronom: getMetronomeMode, setMetronomeMode
• Wiedergabegeschwindigkeit: getPlaybackSpeed, setPlaybackSpeed

• Anmeldelinks und delegierte Zugriffstokens. Admins von Flat for Education können für jeden Nutzer ihrer Organisation einen Anmeldelink oder ein Zugriffstoken erstellen, das im Namen dieses Nutzers handelt: die Grundlage für benutzerdefinierte Portale und Single-Sign-on-Integrationen.
• Japanisch in Hiragana (ja-HIRA) gehört jetzt zu den unterstützten Sprachversionen; öffentliche Kommentare zeigen ihren Moderationsstatus an.
• Audioexporte geben das MP3-Set als Standardspur zurück, wenn eines vorhanden ist. Die Option, nur zwischengespeicherte Exporte anzufordern, wurde entfernt, da Audioexporte jetzt immer aus dem Cache bereitgestellt werden.

• Partitur-Builder. Erstellen Sie ein leeres Partitur, ohne eine MusicXML-Datei zu importieren: Geben Sie eine Liste von Instrumenten an und optional Taktart, Tonart, Tabulatur, Akkorddiagramme und Seitenlayout.
• Flat for Education. Organisationsbenutzer können mit einer Rolle erstellt werden; Arbeitsblätter können ihre Übungen mischen; bei Schülereinreichungen werden die enthaltenen Übungen aufgeführt.

• Wiedergabespuren. Listen Sie die Spuren auf, die Flat automatisch erzeugt und synchronisiert (Wiedergabe als MP3), rufen Sie die Synchronisationspunkte der neuesten Wiedergabedatei ab, und erhalten Sie die CDN-URL eines Exports im Response-Body.
• Flat for Education. Lehrkräfte können die Abgabe eines Schülers oder einer Schülerin zurücksetzen; Klassen melden die Konten, die während einer Synchronisierung nicht hinzugefügt werden konnten; Aufgaben und Abgaben geben ihren Microsoft-Teams-Status und ihre Links aus; Aufgabenkopien können geplant werden; Performance-Abgaben enthalten ihre gespeicherte Audiospur.
• Profile erhalten ein Titelbild, und die id des aktuellen Benutzers kann separat abgerufen werden.

• loadFlatScore akzeptiert einen sharingKey, sodass eine privat geteilte Partitur geladen werden kann
• setTrack, useTrack und seekTrackTo wurden hinzugefügt, um die Audiospur dynamisch festzulegen

• Notenexporte. Lade die Noten einer Aufgabe als CSV- oder Excel-Datei herunter.
• Aufgaben haben einen Typ und ein Titelbild; beim Kopieren einer Aufgabe kann ein bestehender Entwurf mit dem Inhalt einer anderen Aufgabe überschrieben werden.
• Bei Mitwirkenden wird angezeigt, ob ihre Einladung noch aussteht.

• Benotung über die API. Entwurfs- und Endnoten festlegen, eine Abgabe an eine:n Schüler:in zurückgeben und berechnete Kommentarzähler auslesen; die maximale Punktzahl wird zusammen mit der Note gespeichert.
• Abgabekommentare. Kommentare zu einer Abgabe erstellen, auflisten, aktualisieren und löschen.
• Aufgabenoptionen. Werkzeugsätze, ein Wiedergabelimit, maximale Punktzahl, Google-Classroom-Themen, Zuweisung an bestimmte Schüler:innen, gesperrte Vorlagen sowie Details zu LTI-, Canvas- und MusicFirst-Aufgaben.
• Administrator:innen können den Benutzernamen, Namen und die E-Mail-Adresse eines verwalteten Kontos bearbeiten; Benutzerlisten lassen sich nach aktiver Lizenz filtern.
• Die alten Abgabeparameter studentComment und returnFeedback wurden zugunsten der neuen Benotungsaufrufe entfernt.

• Aufgaben archivieren und aus dem Archiv holen sowie den Haupttyp einer Aufgabe auslesen (neue Partitur, Vorlage oder geteiltes Schreiben).
• Organisationsnutzer. Konten mit Vor- und Nachnamen erstellen, Nutzerlisten sortieren und filtern, die zu einem Filter passenden Nutzer zählen und Gruppenmitglieder nach ihrer Synchronisationsquelle filtern (Google Classroom, Microsoft Teams, Clever).
• In den Partiturdetails werden die für die Wiedergabe verwendeten Audio-Samples aufgeführt, mit einer normalisierten Instrumentenliste, die nicht länger von den Samples abhängt.

Steuern Sie den Mix per Code und lesen Sie aus, was sich unter dem Cursor befindet.

• Lautstärke und Stummschaltung: getMasterVolume, setMasterVolume, getPartVolume, setPartVolume, mutePart, unmutePart
• Solo und Hall: setPartSoloMode, unsetPartSoloMode, getPartSoloMode, getPartReverb, setPartReverb
• Inspektion: getMeasureDetails, getNoteDetails
• Hinzugefügte Events: noteDetails, measureDetails, cursorContext

• Die Spezifikation wechselt zu OpenAPI 3.0. Frühere Versionen wurden in OpenAPI 2 (Swagger) beschrieben.
• Partituren geben einen Arrangeur und ihre Wiedergabestatistiken aus; eine Löschung kann so geplant werden, dass sie kurzfristig ausgeführt wird, statt im Papierkorb zu verbleiben.
• Flat for Education. Anhänge zu Aufgaben können Google-Drive-Dateien sein, Klassen enthalten ihre Microsoft-Teams-Informationen, und Bildungskonten geben Vor- und Nachnamen aus.

• Änderungen an Metadaten kommen live im Editor an. Wenn du den Titel, Untertitel, Komponisten, Textdichter oder Lizenztext einer Partitur über die API aktualisierst, wird die Änderung in Echtzeit an geöffnete Editoren übertragen und eine neue Version gespeichert. Beschreibungen können jetzt doppelt so lang sein (2,000 Zeichen).
• Abgaben in Education geben jetzt ihren Status aus (erstellt, abgegeben, zurückgegeben); Revisionsmetadaten liefern das letzte Änderungsereignis zurück.
• Türkisch gehört jetzt zu den unterstützten Sprachen; öffentliche Profile zeigen an, ob ein Konto zum Flat-Team gehört.

• getMIDI hinzugefügt
• getMusicXML gibt jetzt auf oberster Ebene ein Uint8Array zurück — die Antwort enthält keine .data-Eigenschaft mehr
• Der voiceIdx des Cursors heißt jetzt voiceIdxInStaff

Für das Embed-Release aktualisiert.

• Das SDK wird jetzt standardmäßig von flat-embed.com geladen
• Die veraltete edit-Aktion und das edit-Ereignis wurden entfernt
• setNoteColor wurde entfernt

• Mehr Importformate. Guitar Pro-Dateien (GP3, GP4, GP5, GPX, GP), PowerTab-, TuxGuitar- und MuseScore-Dateien können importiert werden, und beim Import kann ein Dateiname übergeben werden.
• Sammlungen können unter einer übergeordneten Sammlung aufgelistet werden und geben ihr Erstellungsdatum zurück; Partituren listen die Sammlungen auf, zu denen sie gehören.
• Kontextbezogene Kommentare werden über eine Kennung statt über einen Index an ein Notensystem angeheftet, und Ressourcenrechte geben an, ob der aufrufende Nutzer ein Mitbearbeiter ist.

• Collections API. Sammlungen erstellen, auflisten, aktualisieren, löschen und wiederherstellen, ihre Partituren auflisten sowie Partituren hinzufügen oder entfernen – mit drei neuen OAuth2-Scopes für Nur-Lesezugriff, Nur-Hinzufügen und Vollzugriff.
• Partituren können aus dem Papierkorb wiederhergestellt werden; wenn du eine Partitur ohne Administratorrechte löschst, wird sie stattdessen nur aus deinem Konto entfernt; eine Kopie kann in eine bestimmte Sammlung abgelegt werden.
• Kommentare können nach Typ gefiltert werden (Dokument oder inline).
• Beim Stimmenexport werden jetzt Stimmenkennungen statt Indizes verwendet, und seit September 2019 liefert die Partiturliste eines Nutzers nur noch öffentliche Partituren zurück.

• Verwaltung von Organisationskonten. Administratoren können verwaltete Konten aktualisieren, löschen oder in private Konten umwandeln; Benutzer- und Einladungsliste verwenden cursorbasierte Paginierung.
• Klassen erhalten einen inaktiven Status, der wieder aktiviert werden kann, und geben ihre Canvas-LMS-Domain und Clever-Sektion an; Aufgaben erhalten einen Entwurfsstatus und einen Anhangstyp für Übungen.
• Profile zeigen ein Design und die gespielten Instrumente an.

• Methode focusScore hinzugefügt, um dem Embed den Tastaturfokus zu geben
• Neue Eigenschaft defaultMode in der Editor-Konfiguration

• Die ersten Education-APIs sind öffentlich. Verwalten Sie Klassen, Aufgaben und Abgaben, Organisationskonten und Einladungen, LTI-Anmeldedaten sowie die Gruppen und Benutzer einer Organisation: alles, was eine Schulintegration braucht.
• Zugriff mit Bereichen. Neue OAuth2-Scopes decken Klassen, Aufgaben und die Organisationsverwaltung ab, jeweils auch mit einer schreibgeschützten Variante, sodass eine Integration nur anfordert, was sie benötigt.

Dein Code kann jetzt prüfen, wie das Embed konfiguriert ist, und es in einen Editor umwandeln.

• Hinzugefügte Methoden: getEmbedConfig, setEditorConfig, edit
• Hinzugefügtes Ereignis: edit

Das SDK kann jetzt Partituren aus MusicXML laden und melden, was der Reader gerade tut.

• Hinzugefügte Methoden: getAutoZoom, setAutoZoom, loadMusicXML, getMusicXML
• Hinzugefügte Events: scoreLoaded, cursorPosition, rangeSelection, pause, stop, fullscreen, print
• Integrationstests hinzugefügt

Die erste öffentliche Veröffentlichung von Flats REST API. Lies und verwalte dein Konto, Partituren, Benutzer und Gruppen aus deinen eigenen Apps und Skripten heraus, mit OAuth2, um im Namen anderer Flat-Nutzer zu handeln.

Alles seitdem ist im API-Änderungsprotokoll festgehalten, und die Entwicklerdokumentation behandelt Authentifizierung, Referenz und Anleitungen.