Developer changelog

Het ontwikkelaarsdashboard is opnieuw opgebouwd rond wat je integratie kan doen. Elke mogelijkheid (Embed, OMR, REST API, Import API, LTI) krijgt een kaart met het bereik, de prijzen en de documentatie, en de mogelijkheden die je app al gebruikt staan vooraan.

• Een nieuwe OMR-sectie op accountniveau, met je taken, je credits en de geschiedenis ervan op één plek, omdat OMR-credits door al je apps worden gedeeld.
• Probeer OMR voordat je code schrijft. De playground neemt een PDF of foto's, toont het aantal pagina's, de kosten per pagina en het saldo dat overblijft, en voert de taak daarna uit zodra je bevestigt. De uitvoer gaat naar MusicXML-downloads; er komt niets in je bibliotheek terecht.
• Duidelijkere app-pagina's. Persoonlijke tokens, OAuth2-referenties en OMR-toegang zijn per applicatie gegroepeerd, waarbij de referenties met het OMR-bereik duidelijk worden aangegeven.

Open het via flat.io/developers.

Onze REST API-specificatie gaat over naar OpenAPI 3.1, de OMR-API sluit de bètaperiode af en opdrachten in Flat for Education gaan verder dan alleen weergeven en aanmaken.

• De OMR-API is stabiel. Endpoints, velden en gedrag volgen nu ons gebruikelijke deprecatieproces vóór een breaking change. Een nieuwe FAQ behandelt credits en facturatie, limieten en verwerkingstijden, herkenningskwaliteit en talen, en commercieel gebruik en privacy.
• Opdrachten lezen, bijwerken en verwijderen in Flat for Education. Als u een opdracht verwijdert, worden ook de inzendingen en de kopieën van leerlingen verwijderd; archiveer de opdracht in plaats daarvan als u het werk wilt bewaren.
• Creditlogboek. Een nieuwe call toont uw creditgeschiedenis; het saldo blijft beschikbaar via de OMR-capabilities-call.
• Finale-bestanden (.musx) kunnen worden geïmporteerd, op basis van best effort, en het importeren van gescande bladmuziek (pdf en afbeeldingen) is gedocumenteerd bij het aanmaken van partituren.
• OpenAPI 3.1. Nullable velden gebruiken de 3.1-syntaxis; tooling die is vastgezet op OpenAPI 3.0 moet worden bijgewerkt. Het veld mimeType is verwijderd uit OMR-bestandsuploads.

• Gegevensbewaring die jij beheert. OMR-taken laten nu zien hoe lang hun bestanden worden bewaard (standaard 30 days), elke MusicXML-taak bevat zijn vervaldatum en je kunt de bestanden en resultaten van een taak verwijderen zodra je ze hebt opgehaald.
• Functiedetectie vóór het inloggen. De OMR-capaciteitenaanroep werkt zonder account en toont de ondersteunde herkenningstalen met hun namen.
• ABC-notatie exporteren voor elke score-revisie, naast MusicXML, MIDI en de andere indelingen. Net als MIDI bevat dit niet de volledige opmaak.
• Free Record-opdrachten kunnen via de API worden geconfigureerd in Flat for Education.
• Fouten van een upstreamprovider (bijvoorbeeld Google Classroom) bevatten nu ook het eigen gelokaliseerde bericht van die provider.

De OMR-engine van Flat is nu programmatisch beschikbaar via de developer API. Verstuur pdf's of foto's, volg de voortgang van de herkenning, controleer de gedetecteerde instrumenten en importeer het resultaat vervolgens als een bewerkbare partituur in een Flat-bibliotheek, of exporteer het als MusicXML of MIDI. Het is hetzelfde interne model dat het importeren van pdf's en foto's in de editor aandrijft, en is nu op schaal beschikbaar voor je eigen apps en workflows.

De speciale OMR API (v2.24.0) bouwt voort op de pdf-import op de achtergrond die in v2.23.0 aan het aanmaken van partituren is toegevoegd: vraag om taakondersteuning bij het importeren van een bestand en poll de taak totdat de partituur klaar is. Zie de API-wijzigingslog voor de details van beide releases.

De grootste specificatie-update sinds 2024, waarmee de API weer aansluit op twee jaar productwijzigingen.

• Import uit 15+ formaten. Guitar Pro, MuseScore, ABC-notatie, PowerTab, Capella, MEI, Overture, TablEdit, Band-in-a-Box, Karaoke MIDI, MuseData, Score Writer, Bagpipe Music Writer en Encore komen naast MusicXML en MIDI beschikbaar, en partituren kunnen worden geëxporteerd als native .flat-bestanden.
• Virtuele verzamelingen. Alle partituren, samenwerkingen en vind-ik-leuks vervangen de oude mappenhiërarchie in de bibliotheek, in lijn met de vernieuwde Flat-bibliotheek.
• Flat for Education. Uitvoeringsopdrachten met audio- of video-opnamen en opties voor backingtrack, metronoom en snelheid; groepsinzendingen voor gezamenlijk schrijven; instructies met rich text; subgroepen van studenten; geplande en individueel toegewezen Microsoft Teams-opdrachten; uitgebreide beschrijvingen en opdrachttypen in de resourcebibliotheek.
• Geïntegreerde LTI-configuratie voor LTI 1.1 en 1.3, inclusief dynamische registratie. De eerdere aanroepen voor LTI 1.1-inloggegevens zijn verouderd.
• Jaarlijkse statistieken over partituren, aantallen openbare partituren op profielen en verwijdering van enkele al lang verouderde velden.

• De methoden getMP3 en getWAV toegevoegd voor audio-export
• De gebeurtenis exportProgress toegevoegd, zodat een lange export de voortgang kan tonen

• Gebruikersscorelijsten zijn openbare profielen. Bij het opvragen van de partituren van een gebruiker krijg je nu alleen nog diens openbare partituren terug, met nieuwe paginering en sortering, zoals aangekondigd in 2020.
• Partituurdetails tonen de bewerk-URL, instrumentnamen en een eventuele geplande verwijderdatum; collecties geven hun aantal partituren door; openbare profielen tonen het aantal likes en afspeelbeurten.
• Flat for Education. Filter de bronnenbibliotheek op opdrachttype, vak en leerjaar; bronnen bevatten een beschrijving van delen en privacyopties; opdrachten kunnen het afspelen van noten en audiotracks beperken; inzendingen ondersteunen LTI 1.1- en 1.3-beoordelingsservices.

• Gepagineerde likes op gebruikersprofielen, en het product dat een gebruiker gebruikt in de accountgegevens.
• Rechten op resources geven aan of de aanroeper de eigenaar is, een gebruikersmedewerker of een groepsmedewerker, met de datum waarop elke medewerker is toegevoegd. Scoredetails bevatten nu ook de hoofdtoonsoort, markeringsdatum en organisatie.
• Flat for Education. Uitnodigingen kunnen meerdere keren worden hergebruikt; inzendingen krijgen een beoordeelde status plus afspeel- en LTI-details; een opdracht kan alleen naar de resourcebibliotheek worden gekopieerd als die daar nog niet staat; organisaties krijgen hun eigen resourcebibliotheken met een privacyniveau voor de hele organisatie.

Lees de structuur van de geladen partituur uit je code.

• Partijen en stemmen: getNbParts, getPartsUuids, getMeasureVoicesUuids
• Noten: getMeasureNbNotes, getNoteData, playbackPositionToNoteIdx
• Nieuwe URL-parameter noAudio schakelt audioweergave uit
• Probleem opgelost waarbij setMasterVolume de verkeerde onderliggende methode aanriep

• Ondersteuning voor jQuery in de constructor verwijderd — geef in plaats daarvan een DOM-element of de id ervan door
• De gepubliceerde npm-module bevat TypeScript-typen
• Aparte ES- en UMD-builds

• Maak LTI-links aan vanuit items in de bronnenbibliotheek van Flat for Education, om ze rechtstreeks in een LMS-cursus te plaatsen.
• Het maximale cijfer voor een opdracht gaat van 100 naar 10.000 punten.
• Partituurmetadata (subtitel, componist, tekstschrijver, arrangeur, beschrijving, licentie…) kunnen nu ook via de API worden gewist, niet alleen ingesteld.

• Resource Library API (bèta). Blader door resourcebibliotheken van Flat for Education en beheer ze, met twee nieuwe OAuth2-scopes voor volledige toegang en alleen-lezen-toegang. Opdrachten kunnen naar de resourcebibliotheek worden gekopieerd.
• Testleerlingen. Maak testaccounts voor leerlingen aan in een klas om opdrachten uit te proberen zoals een leerling die zou zien.
• Opdrachten geven aan wat je ermee kunt doen (bewerken, publiceren, archiveren…), of hun bijlagen speciale kopieën zijn en welke problemen er zijn opgetreden. De indieningsgeschiedenis registreert de bron van een wijziging wanneer die afkomstig is van Google Classroom, Microsoft Teams of een LMS.
• Bij het resetten van een indiening blijft die behouden in plaats van te worden verwijderd; klassenmetadata (niveau, vaardigheden, grootte) en Microsoft-aanmeldgegevens van accounts worden beschikbaar gemaakt.
• Partituurrevisies geven hun begin- en einddatum terug; partiturbouwers kunnen kwarttonen inschakelen; kopieën kunnen de oorspronkelijke titel behouden.

• Maten: getNbMeasures, getMeasuresUuids
• Navigatie: goLeft, goRight, scrollToCursor
• Metronoom: getMetronomeMode, setMetronomeMode
• Afspeelsnelheid: getPlaybackSpeed, setPlaybackSpeed

• Aanmeldlinks en gedelegeerde toegangstokens. Beheerders van Flat for Education kunnen een aanmeldlink maken voor elke gebruiker in hun organisatie, of een toegangstoken dat namens die gebruiker handelt: de basis voor aangepaste portalen en single-sign-on-integraties.
• Japans in hiragana (ja-HIRA) is toegevoegd aan de ondersteunde landinstellingen; openbare reacties tonen hun moderatiestatus.
• Audio-exporten geven de MP3-set terug als standaardtrack wanneer die beschikbaar is. De optie om alleen gecachte exporten op te vragen is verwijderd, omdat audio-exporten nu altijd uit de cache worden geleverd.

• Partituurbouwer. Maak een lege partituur zonder een MusicXML-bestand te importeren: geef een lijst met instrumenten op en optioneel de maatsoort, toonsoort, tablatuur, akkoorddiagrammen en paginalay-out.
• Flat for Education. Organisatiegebruikers kunnen met een rol worden aangemaakt; werkbladen kunnen hun oefeningen door elkaar husselen; inzendingen van leerlingen vermelden welke oefeningen ze bevatten.

• Afspeeltracks. Geef een lijst van de tracks die Flat automatisch genereert en synchroniseert (afspelen als MP3), haal de synchronisatiepunten van het nieuwste afspeelbestand op en ontvang de CDN-URL van een export in de response-body.
• Flat for Education. Docenten kunnen de inzending van een leerling resetten; klassen melden welke accounts tijdens een synchronisatie niet konden worden toegevoegd; opdrachten en inzendingen tonen hun Microsoft Teams-status en -links; opdrachtkopieën kunnen worden ingepland; performance-inzendingen bevatten hun opgeslagen audiotrack.
• Profielen krijgen een omslagafbeelding en de id van de huidige gebruiker kan afzonderlijk worden opgehaald.

• loadFlatScore accepteert een sharingKey, zodat een privé gedeelde partituur kan worden geladen
• setTrack, useTrack en seekTrackTo toegevoegd om de audiotrack dynamisch in te stellen

• Cijferexport. Download de cijfers van een opdracht als CSV- of Excel-bestand.
• Opdrachten bevatten hun type en een omslagafbeelding; bij het kopiëren van een opdracht kun je een bestaand concept overschrijven met de inhoud van een andere opdracht.
• Bij medewerkers wordt weergegeven of hun uitnodiging nog in behandeling is.

• Beoordeling via de API. Stel concept- en definitieve cijfers in, stuur een inzending terug naar een leerling en lees berekende tellers voor reacties; het maximumaantal punten wordt samen met het cijfer opgeslagen.
• Reacties op inzendingen. Maak reacties op een inzending aan, bekijk ze in een lijst, werk ze bij en verwijder ze.
• Opdrachtopties. Toolsets, een afspeellimiet, maximumaantal punten, Google Classroom-onderwerpen, toewijzen aan specifieke leerlingen, vergrendelde sjablonen en details van LTI-, Canvas- en MusicFirst-opdrachten.
• Beheerders kunnen de gebruikersnaam, naam en het e-mailadres van een beheerd account bewerken; gebruikerslijsten kunnen worden gefilterd op actieve licentie.
• De oude inzendingsparameters studentComment en returnFeedback zijn verwijderd ten gunste van de nieuwe beoordelingsaanroepen.

• Archiveer en dearchiveer opdrachten, en lees het hoofdtype van een opdracht uit (nieuwe partituur, sjabloon of gedeeld schrijven).
• Organisatiegebruikers. Maak accounts aan met een voor- en achternaam, sorteer en filter gebruikerslijsten, tel de gebruikers die aan een filter voldoen en filter groepsleden op hun synchronisatiebron (Google Classroom, Microsoft Teams, Clever).
• In de partitruurdetails worden de audiosamples vermeld die voor afspelen worden gebruikt, met een genormaliseerde instrumentenlijst die niet langer van de samples afhangt.

Regel de mix vanuit je code en lees wat er onder de cursor staat.

• Volume en dempen: getMasterVolume, setMasterVolume, getPartVolume, setPartVolume, mutePart, unmutePart
• Solo en galm: setPartSoloMode, unsetPartSoloMode, getPartSoloMode, getPartReverb, setPartReverb
• Inspectie: getMeasureDetails, getNoteDetails
• Toegevoegde events: noteDetails, measureDetails, cursorContext

• De specificatie gaat over naar OpenAPI 3.0. Eerdere versies werden beschreven in OpenAPI 2 (Swagger).
• Partituren geven nu een arrangeur en diens afspeelstatistieken weer; een verwijdering kan zo worden gepland dat die binnenkort wordt uitgevoerd in plaats van in de prullenbak te blijven staan.
• Flat for Education. Bijlagen bij opdrachten kunnen Google Drive-bestanden zijn, klassen bevatten hun Microsoft Teams-gegevens en Education-accounts geven een voor- en achternaam door.

• Metadatawijzigingen komen live in de editor terecht. Als je via de API de titel, ondertitel, componist, tekstschrijver of licentietekst van een partituur bijwerkt, worden die wijzigingen in realtime naar open editors gestuurd en wordt er een nieuwe versie opgeslagen. Beschrijvingen kunnen twee keer zo lang zijn (2,000 tekens).
• Inzendingen in Education geven nu hun status weer (created, turned in, returned); revisiemetadata geven de laatste wijzigingsgebeurtenis terug.
• Turks is toegevoegd aan de ondersteunde talen; openbare profielen vermelden of een account tot het Flat-team behoort.

• getMIDI toegevoegd
• getMusicXML retourneert nu een Uint8Array op het hoogste niveau — de respons bevat niet langer een eigenschap .data
• De voiceIdx van de cursor heet nu voiceIdxInStaff

Bijgewerkt voor de embed-release.

• De SDK wordt nu standaard geladen vanaf flat-embed.com
• De verouderde actie edit en gebeurtenis edit zijn verwijderd
• setNoteColor is verwijderd

• Meer importformaten. Guitar Pro-bestanden (GP3, GP4, GP5, GPX, GP), PowerTab-, TuxGuitar- en MuseScore-bestanden kunnen worden geïmporteerd, en bij import kan een bestandsnaam worden opgegeven.
• Collecties kunnen onder een bovenliggende collectie worden weergegeven en geven hun aanmaakdatum door; partituren vermelden bij welke collecties ze horen.
• Contextuele opmerkingen worden aan een notenbalk verankerd met een identifier in plaats van een index, en bronrechten geven aan of de aanroeper een medewerker is.

• Collections API. Maak collecties aan, bekijk, werk ze bij, verwijder en herstel ze, bekijk de partituren erin en voeg partituren toe of verwijder ze, met drie nieuwe OAuth2-scopes voor alleen-lezen, alleen-toevoegen en volledige toegang.
• Partituren kunnen uit de prullenbak worden hersteld; als je een partituur zonder beheerdersrechten verwijdert, wordt die in plaats daarvan losgekoppeld van je account; een kopie kan op een specifieke collectie worden gericht.
• Reacties kunnen op type worden gefilterd (document of inline).
• Bij partexport worden nu part-ID's gebruikt in plaats van indexen, en vanaf september 2019 geeft de partiturenlijst van een gebruiker alleen nog openbare partituren terug.

• Beheer van organisatieaccounts. Beheerders kunnen beheerde accounts bijwerken, verwijderen of omzetten naar consumentenaccounts; gebruikers- en uitnodigingslijsten gebruiken cursorgebaseerde paginering.
• Klassen krijgen een inactieve status die opnieuw kan worden geactiveerd, en geven hun Canvas LMS-domein en Clever-sectie door; opdrachten krijgen een conceptstatus en een bijlagetype voor oefeningen.
• Profielen geven een thema en de bespeelde instrumenten weer.

• Methode focusScore toegevoegd om de embed toetsenbordfocus te geven
• Nieuwe eigenschap defaultMode in de editorconfiguratie

• De eerste Education-API's zijn openbaar. Beheer klassen, opdrachten en inzendingen, organisatieaccounts en uitnodigingen, LTI-gegevens en de groepen en gebruikers van een organisatie: alles wat een schoolintegratie nodig heeft.
• Toegang met scopes. Nieuwe OAuth2-scopes dekken klassen, opdrachten en organisatiebeheer, elk met een alleen-lezenvariant, zodat een integratie alleen vraagt wat nodig is.

Je code kan nu controleren hoe de embed is geconfigureerd en die omzetten naar een editor.

• Toegevoegde methoden: getEmbedConfig, setEditorConfig, edit
• Toegevoegd event: edit

De SDK kan nu partituren laden vanuit MusicXML en doorgeven wat de lezer aan het doen is.

• Methoden toegevoegd: getAutoZoom, setAutoZoom, loadMusicXML, getMusicXML
• Events toegevoegd: scoreLoaded, cursorPosition, rangeSelection, pause, stop, fullscreen, print
• Integratietests toegevoegd

De eerste openbare release van de REST API van Flat. Lees en beheer je account, partituren, gebruikers en groepen vanuit je eigen apps en scripts, met OAuth2 om namens andere Flat-gebruikers te handelen.

Alles sindsdien is vastgelegd in de API-wijzigingslog, en de ontwikkelaarsdocumentatie behandelt authenticatie, de referentie en handleidingen.