Developer changelog

La dashboard per sviluppatori è stata riprogettata in base a ciò che la tua integrazione può fare. Ogni funzionalità (Embed, OMR, REST API, Import API, LTI) ha una scheda con ambito, prezzi e documentazione, e quelle che la tua app usa già compaiono per prime.

• Una nuova sezione OMR a livello di account, con i tuoi processi, i tuoi crediti e il relativo storico in un unico posto, perché i crediti OMR sono condivisi da tutte le tue app.
• Prova OMR prima di scrivere codice. Il playground accetta un PDF o delle foto, mostra il numero di pagine, il costo per pagina e il saldo rimanente, quindi avvia il processo dopo la conferma. L'output viene fornito come download MusicXML e non viene aggiunto alla tua libreria.
• Pagine delle app più chiare. I token personali, le credenziali OAuth2 e l'accesso OMR sono raggruppati per applicazione, con un'indicazione chiara delle credenziali che includono l'ambito OMR.

Aprila da flat.io/developers.

La specifica della nostra API REST passa a OpenAPI 3.1, l’API OMR chiude il periodo beta e gli assignment di Flat for Education si aprono oltre la semplice consultazione e creazione.

• L’API OMR è stabile. Endpoint, campi e comportamento seguono ora il nostro consueto processo di deprecazione prima di qualsiasi modifica incompatibile. Una nuova FAQ copre crediti e fatturazione, limiti e tempi di elaborazione, qualità del riconoscimento e lingue, uso commerciale e privacy.
• Leggere, modificare ed eliminare gli assignment in Flat for Education. L’eliminazione di un assignment rimuove anche i relativi elaborati e le copie degli studenti; per conservare il lavoro, archiviatelo.
• Registro dei crediti. Una nuova chiamata elenca lo storico dei crediti; il saldo resta nella chiamata delle funzionalità OMR.
• I file Finale (.musx) possono essere importati, in modalità best-effort, e l’importazione di musica scansionata (PDF e immagini) è documentata nella creazione dello spartito.
• OpenAPI 3.1. I campi nullable usano la sintassi 3.1; gli strumenti bloccati su OpenAPI 3.0 devono essere aggiornati. Il campo mimeType è stato rimosso dagli upload di file OMR.

• Controllo della conservazione dei dati. I processi OMR ora indicano per quanto tempo vengono conservati i relativi file (30 days per impostazione predefinita), ogni processo MusicXML include la propria data di scadenza e puoi eliminare file e risultati di un processo non appena li hai recuperati.
• Rilevamento delle funzionalità prima dell'accesso. La chiamata alle capacità OMR funziona anche senza account e restituisce l'elenco delle lingue di riconoscimento supportate con i relativi nomi.
• Esportazione in notazione ABC per qualsiasi revisione della partitura, insieme a MusicXML, MIDI e agli altri formati. Come MIDI, non include l'impaginazione completa.
• I compiti Free Record possono essere configurati tramite API in Flat for Education.
• Gli errori provenienti da un provider upstream (ad esempio Google Classroom) ora includono il messaggio localizzato del provider stesso.

Il motore OMR di Flat è ora disponibile a livello programmatico tramite la API per sviluppatori. Invia PDF o foto, monitora l'avanzamento del riconoscimento, controlla gli strumenti rilevati, quindi importa il risultato come partitura modificabile in una libreria Flat oppure esportalo in MusicXML o MIDI. È lo stesso modello sviluppato internamente che gestisce l'importazione di PDF e foto nell'editor, ora disponibile su larga scala per le tue app e i tuoi flussi di lavoro.

L'API OMR dedicata (v2.24.0) si basa sull'importazione PDF in background aggiunta alla creazione delle partiture nella v2.23.0: richiedi il supporto delle attività durante l'importazione di un file e interroga periodicamente l'attività finché la partitura non è pronta. Consulta il changelog dell'API per i dettagli di entrambe le versioni.

Il più grande aggiornamento delle specifiche dal 2024, che allinea l'API a due anni di evoluzione del prodotto.

• Importazione da oltre 15 formati. Guitar Pro, MuseScore, notazione ABC, PowerTab, Capella, MEI, Overture, TablEdit, Band-in-a-Box, Karaoke MIDI, MuseData, Score Writer, Bagpipe Music Writer ed Encore si aggiungono a MusicXML e MIDI, e le partiture possono essere esportate come file .flat nativi.
• Raccolte virtuali. Tutte le partiture, le collaborazioni e i Mi piace sostituiscono la vecchia gerarchia di cartelle nella libreria, in linea con la libreria di Flat riprogettata.
• Flat for Education. Compiti di esecuzione con registrazioni audio o video e opzioni per base musicale, metronomo e velocità; consegne di gruppo per la scrittura condivisa; istruzioni in testo avanzato; sottogruppi di studenti; compiti Microsoft Teams pianificati e assegnati a singoli destinatari; descrizioni avanzate e tipi di compito nella libreria delle risorse.
• Configurazione LTI unificata per LTI 1.1 e 1.3, inclusa la registrazione dinamica. Le precedenti chiamate delle credenziali LTI 1.1 sono deprecate.
• Statistiche annuali sulle partiture, conteggio delle partiture pubbliche sui profili e rimozione di alcuni campi deprecati da tempo.

• Aggiunti i metodi getMP3 e getWAV per l'esportazione audio
• Aggiunto l'evento exportProgress, così un'esportazione lunga può mostrare l'avanzamento

• Gli elenchi dei punteggi degli utenti sono profili pubblici. L'elenco degli spartiti di un utente ora restituisce solo i suoi spartiti pubblici, con nuove opzioni di paginazione e ordinamento, come annunciato nel 2020.
• I dettagli degli spartiti mostrano l'URL di modifica, i nomi degli strumenti ed eventuali date di eliminazione pianificate; le raccolte indicano il numero di spartiti; i profili pubblici mostrano il numero di Mi piace e di riproduzioni.
• Flat for Education. Filtra la libreria di risorse per tipo di compito, materia e livello scolastico; le risorse includono una descrizione della condivisione e le opzioni di privacy; i compiti possono limitare la riproduzione delle note e le tracce audio; le consegne supportano i servizi di valutazione LTI 1.1 e 1.3.

• "Mi piace" paginati sui profili utente e prodotto usato dall'utente nei dettagli del suo account.
• I diritti sulle risorse indicano se il chiamante è il proprietario, un collaboratore utente o un collaboratore di gruppo, con la data di aggiunta di ciascun collaboratore. I dettagli della partitura aggiungono l'armatura di chiave principale, la data di evidenziazione e l'organizzazione.
• Flat for Education. Gli inviti possono essere riutilizzati più volte; le consegne aggiungono uno stato di valutazione, oltre ai dettagli di riproduzione e LTI; un compito può essere copiato nella libreria di risorse solo se non è già presente; le organizzazioni ottengono librerie di risorse dedicate con un livello di privacy esteso a tutta l'organizzazione.

Leggi la struttura della partitura caricata dal tuo codice.

• Parti e voci: getNbParts, getPartsUuids, getMeasureVoicesUuids
• Note: getMeasureNbNotes, getNoteData, playbackPositionToNoteIdx
• Il nuovo parametro URL noAudio disattiva la riproduzione audio
• Corretto setMasterVolume, che chiamava il metodo sottostante sbagliato

• Rimosso il supporto per jQuery nel costruttore — passa invece un elemento DOM o il suo id
• Il modulo npm pubblicato include i tipi TypeScript
• Build ES e UMD separate

• Crea link LTI dagli elementi della raccolta risorse di Flat for Education, per inserirli direttamente in un corso LMS.
• Il voto massimo di un compito passa da 100 a 10.000 punti.
• I metadati della partitura (sottotitolo, compositore, paroliere, arrangiatore, descrizione, licenza…) ora possono anche essere cancellati tramite l’API, non solo impostati.

• API Resource Library (beta). Sfoglia e gestisci le librerie di risorse di Flat for Education, con due nuovi scope OAuth2 per l’accesso completo e in sola lettura. Gli assignment possono essere copiati nella libreria di risorse.
• Studenti di test. Crea account studente di test in una classe per provare gli assignment come farebbe uno studente.
• Gli assignment indicano quali azioni sono disponibili (modificare, pubblicare, archiviare…), se i loro allegati sono copie dedicate e qualsiasi problema riscontrato. La cronologia delle consegne registra l’origine di una modifica quando proviene da Google Classroom, Microsoft Teams o un LMS.
• Il ripristino di una consegna la mantiene al suo posto invece di eliminarla; i metadati della classe (livello, competenze, dimensione) e i dettagli di accesso Microsoft sugli account sono esposti.
• Le revisioni della partitura restituiscono le date di inizio e fine; i generatori di partiture possono abilitare i quarti di tono; le copie possono mantenere il titolo originale.

• Battute: getNbMeasures, getMeasuresUuids
• Navigazione: goLeft, goRight, scrollToCursor
• Metronomo: getMetronomeMode, setMetronomeMode
• Velocità di riproduzione: getPlaybackSpeed, setPlaybackSpeed

• Link di accesso e token di accesso delegati. Gli amministratori di Flat for Education possono creare un link di accesso per qualsiasi utente della propria organizzazione, oppure un token di accesso che agisce per conto di quell'utente: la base per portali personalizzati e integrazioni single sign-on.
• Il giapponese in hiragana (ja-HIRA) si aggiunge alle lingue supportate; i commenti pubblici mostrano il loro stato di moderazione.
• Le esportazioni audio restituiscono il set MP3 come traccia predefinita quando disponibile. L'opzione per richiedere solo le esportazioni in cache è stata rimossa, poiché le esportazioni audio vengono ora sempre fornite dalla cache.

• Generatore di spartiti. Crea uno spartito vuoto senza importare un file MusicXML: fornisci un elenco di strumenti e, facoltativamente, l'indicazione di tempo, l'armatura di chiave, la tablatura, i diagrammi degli accordi e l'impaginazione.
• Flat for Education. Gli utenti dell'organizzazione possono essere creati con un ruolo; i fogli di lavoro possono mescolare i loro esercizi; gli invii degli studenti elencano gli esercizi che contengono.

• Tracce di riproduzione. Elenca le tracce generate e sincronizzate automaticamente da Flat (riproduzione in MP3), recupera i punti di sincronizzazione dell'ultimo file di riproduzione e ottieni l'URL CDN di un'esportazione nel corpo della risposta.
• Flat for Education. Gli insegnanti possono reimpostare la consegna di uno studente; le classi segnalano gli account che non è stato possibile aggiungere durante una sincronizzazione; compiti e consegne espongono il loro stato e i link Microsoft Teams; le copie dei compiti possono essere programmate; le consegne di performance includono la traccia audio salvata.
• I profili ora includono un'immagine di copertina e l'id dell'utente corrente può essere recuperato separatamente.

• loadFlatScore accetta una sharingKey, così è possibile caricare uno spartito condiviso privatamente
• Aggiunti setTrack, useTrack e seekTrackTo per impostare dinamicamente la traccia audio

• Esportazione dei voti. Scarica i voti di un compito come file CSV o Excel.
• I compiti includono il loro tipo e un'immagine di copertina; copiando un compito è possibile sovrascrivere una bozza esistente con il contenuto di un altro compito.
• Per i collaboratori viene indicato se il loro invito è ancora in attesa.

• Valutazione tramite API. Imposta voti provvisori e finali, restituisci una consegna allo studente e leggi i contatori calcolati dei commenti; il punteggio massimo viene memorizzato con il voto.
• Commenti alle consegne. Crea, elenca, aggiorna ed elimina i commenti su una consegna.
• Opzioni di compito. Set di strumenti, limite di riproduzione, punteggio massimo, argomenti di Google Classroom, assegnazione a studenti specifici, modelli bloccati e dettagli delle assegnazioni LTI, Canvas e MusicFirst.
• Gli amministratori possono modificare nome utente, nome ed email di un account gestito; gli elenchi degli utenti possono essere filtrati in base alla licenza attiva.
• I vecchi parametri di consegna studentComment e returnFeedback sono stati rimossi a favore delle nuove chiamate di valutazione.

• Archivia e ripristina i compiti, e leggi il tipo principale di un compito (nuovo spartito, modello o scrittura condivisa).
• Utenti dell'organizzazione. Crea account con nome e cognome, ordina e filtra gli elenchi di utenti, conta gli utenti che corrispondono a un filtro e filtra i membri dei gruppi in base alla loro origine di sincronizzazione (Google Classroom, Microsoft Teams, Clever).
• I dettagli dello spartito elencano i campioni audio usati per la riproduzione, con un elenco normalizzato degli strumenti che non dipende più dai campioni.

Controlla il mix dal tuo codice e leggi cosa si trova sotto il cursore.

• Volume e mute: getMasterVolume, setMasterVolume, getPartVolume, setPartVolume, mutePart, unmutePart
• Solo e riverbero: setPartSoloMode, unsetPartSoloMode, getPartSoloMode, getPartReverb, setPartReverb
• Ispezione: getMeasureDetails, getNoteDetails
• Eventi aggiunti: noteDetails, measureDetails, cursorContext

• La specifica passa a OpenAPI 3.0. Le versioni precedenti erano descritte in OpenAPI 2 (Swagger).
• Le partiture espongono un arrangiatore e le relative statistiche di riproduzione; l'eliminazione può essere programmata per avvenire a breve invece di restare nel cestino.
• Flat for Education. Gli allegati dei compiti possono essere file di Google Drive, le classi includono i dettagli di Microsoft Teams e gli account Education espongono nome e cognome.

• Le modifiche ai metadati arrivano all'editor in tempo reale. Quando aggiorni tramite API il titolo, il sottotitolo, il compositore, il paroliere o il testo della licenza di una partitura, le modifiche vengono inviate in tempo reale agli editor aperti e viene salvata una nuova versione. Le descrizioni possono essere lunghe il doppio (2,000 caratteri).
• Le consegne di Education espongono il loro stato (created, turned in, returned); i metadati delle revisioni restituiscono l'ultimo evento di modifica.
• Il turco si aggiunge alle lingue supportate; i profili pubblici indicano se un account appartiene al team di Flat.

• Aggiunto getMIDI
• getMusicXML ora restituisce un Uint8Array al livello superiore — la risposta non include più una proprietà .data
• voiceIdx del cursore ora è voiceIdxInStaff

Aggiornato per la release dell'embed.

• L'SDK ora viene caricato da flat-embed.com per impostazione predefinita
• Rimossi l'azione edit e l'evento edit, entrambi deprecati
• Rimosso setNoteColor

• Più formati di importazione. È possibile importare file Guitar Pro (GP3, GP4, GP5, GPX, GP), PowerTab, TuxGuitar e MuseScore e specificare un nome file per l’importazione.
• Le raccolte possono essere elencate all’interno di una raccolta padre e indicano la data di creazione; gli spartiti elencano le raccolte a cui appartengono.
• I commenti contestuali sono ancorati a un rigo tramite identificatore anziché indice e i diritti della risorsa indicano se il chiamante è un collaboratore.

• API Collections. Crea, elenca, aggiorna, elimina e ripristina le raccolte, visualizza l’elenco delle relative partiture e aggiungi o rimuovi partiture, con tre nuovi scope OAuth2 per accesso in sola lettura, sola aggiunta e accesso completo.
• Le partiture possono essere ripristinate dal cestino; eliminare una partitura senza diritti di amministrazione la rimuove invece dalla condivisione con il tuo account; una copia può essere destinata a una raccolta specifica.
• I commenti possono essere filtrati per tipo (documento o in linea).
• Le esportazioni delle parti ora usano identificatori di parte invece di indici e, da settembre 2019, l’elenco delle partiture di un utente restituisce solo partiture pubbliche.

• Gestione degli account dell’organizzazione. Gli amministratori possono aggiornare gli account gestiti, eliminarli oppure convertirli in account consumer; gli elenchi di utenti e inviti usano la paginazione basata su cursore.
• Le classi hanno ora uno stato inattivo che può essere riattivato e riportano il dominio Canvas LMS e la sezione Clever; i compiti hanno ora uno stato bozza e un tipo di allegato esercizio.
• I profili espongono un tema e gli strumenti suonati.

• Aggiunto il metodo focusScore per dare il focus da tastiera all'embed
• Nuova proprietà defaultMode nella configurazione dell'editor

• Le prime API Education sono pubbliche. Gestisci classi, compiti e consegne, account e inviti dell'organizzazione, credenziali LTI, nonché gruppi e utenti di un'organizzazione: tutto ciò di cui un'integrazione scolastica ha bisogno.
• Accesso con ambiti definiti. I nuovi scope OAuth2 coprono classi, compiti e amministrazione dell'organizzazione, ciascuno con una variante in sola lettura, così un'integrazione richiede solo ciò di cui ha bisogno.

Il tuo codice può ora controllare come è configurato l'embed e trasformarlo in un editor.

• Metodi aggiunti: getEmbedConfig, setEditorConfig, edit
• Evento aggiunto: edit

L'SDK ora può caricare spartiti da MusicXML e segnalare cosa sta facendo il lettore.

• Metodi aggiunti: getAutoZoom, setAutoZoom, loadMusicXML, getMusicXML
• Eventi aggiunti: scoreLoaded, cursorPosition, rangeSelection, pause, stop, fullscreen, print
• Aggiunti test di integrazione

La prima release pubblica della REST API di Flat. Leggi e gestisci il tuo account, le partiture, gli utenti e i gruppi dalle tue app e dai tuoi script, con OAuth2 per agire per conto di altri utenti di Flat.

Tutto ciò che è stato introdotto da allora è riportato nel changelog dell’API, mentre la documentazione per sviluppatori copre autenticazione, riferimento e guide.