Dziennik zmian dla deweloperów

Panel deweloperski został przebudowany wokół możliwości Twojej integracji. Każda funkcja (Embed, OMR, REST API, Import API, LTI) ma własną kartę z zakresem, cennikiem i dokumentacją, a te, z których Twoja aplikacja już korzysta, są pokazane jako pierwsze.

• Nowa sekcja OMR na poziomie konta, z Twoimi zadaniami, kredytami i ich historią w jednym miejscu, ponieważ kredyty OMR są współdzielone przez wszystkie Twoje aplikacje.
• Wypróbuj OMR, zanim napiszesz kod. Playground przyjmuje plik PDF lub zdjęcia, pokazuje liczbę stron, koszt za stronę i saldo, które pozostanie, a następnie uruchamia zadanie po potwierdzeniu. Wynik jest dostępny do pobrania jako MusicXML, nic nie trafia do Twojej biblioteki.
• Czytelniejsze strony aplikacji. Tokeny osobiste, dane uwierzytelniające OAuth2 i dostęp do OMR są pogrupowane według aplikacji, a dane uwierzytelniające z zakresem OMR są wyraźnie oznaczone.

Otwórz go z poziomu flat.io/developers.

Nasza specyfikacja REST API przechodzi na OpenAPI 3.1, OMR API kończy okres beta, a zadania w Flat for Education oferują już więcej niż tylko listowanie i tworzenie.

• OMR API jest stabilne. Endpointy, pola i działanie podlegają teraz naszemu standardowemu procesowi wycofywania przed wprowadzeniem jakiejkolwiek niekompatybilnej zmiany. Nowe FAQ opisuje kredyty i rozliczenia, limity i czasy przetwarzania, jakość rozpoznawania i języki oraz zastosowania komercyjne i prywatność.
• Odczytuj, aktualizuj i usuwaj zadania w Flat for Education. Usunięcie zadania usuwa także jego zgłoszenia i kopie uczniów; zamiast tego zarchiwizuj je, jeśli chcesz zachować pracę.
• Rejestr kredytów. Nowe wywołanie pokazuje historię kredytów; saldo pozostaje dostępne w wywołaniu możliwości OMR.
• Pliki Finale (.musx) można importować w miarę możliwości, a import skanowanej muzyki (PDF i obrazów) został udokumentowany przy tworzeniu partytury.
• OpenAPI 3.1. Pola nullable używają składni 3.1; narzędzia przypięte do OpenAPI 3.0 wymagają aktualizacji. Pole mimeType zostało usunięte z przesyłania plików OMR.

• Przechowywanie danych pod Twoją kontrolą. Zadania OMR informują teraz, jak długo ich pliki są przechowywane (domyślnie 30 dni), każde zadanie MusicXML zawiera datę wygaśnięcia, a pliki i wyniki zadania możesz usunąć od razu po ich pobraniu.
• Wykrywanie funkcji przed zalogowaniem. Wywołanie możliwości OMR działa bez konta i wyświetla obsługiwane języki rozpoznawania wraz z ich nazwami.
• Eksport notacji ABC dla każdej wersji partytury, obok MusicXML, MIDI i innych formatów. Podobnie jak MIDI nie zawiera pełnego opracowania graficznego zapisu nutowego.
• Zadania Free Record można konfigurować przez API w Flat for Education.
• Błędy pochodzące od zewnętrznego dostawcy (na przykład Google Classroom) zawierają teraz własny zlokalizowany komunikat tego dostawcy.

Silnik OMR w Flat jest teraz dostępny programowo przez API deweloperskie. Wysyłaj pliki PDF lub zdjęcia, śledź postęp rozpoznawania, sprawdzaj wykryte instrumenty, a następnie importuj wynik jako edytowalną partyturę do biblioteki Flat albo eksportuj MusicXML lub MIDI. To ten sam wewnętrzny model, który odpowiada za import plików PDF i zdjęć w edytorze, teraz dostępny na dużą skalę dla własnych aplikacji i przepływów pracy.

Dedykowane API OMR (v2.24.0) rozwija import plików PDF w tle, dodany przy tworzeniu partytur w v2.23.0: poproś o obsługę zadań podczas importowania pliku i odpytuj zadanie, aż partytura będzie gotowa. Szczegóły obu wydań znajdziesz w dzienniku zmian API.

Największa aktualizacja specyfikacji od 2024 roku, dostosowująca API do dwóch lat zmian w produkcie.

• Import z ponad 15 formatów. Guitar Pro, MuseScore, notacja ABC, PowerTab, Capella, MEI, Overture, TablEdit, Band-in-a-Box, Karaoke MIDI, MuseData, Score Writer, Bagpipe Music Writer i Encore dołączają do MusicXML i MIDI, a partytury można eksportować jako natywne pliki .flat.
• Kolekcje wirtualne. Wszystkie partytury, współprace i polubienia zastępują starszą hierarchię folderów w bibliotece, zgodnie z przeprojektowaną biblioteką Flat.
• Flat for Education. Zadania wykonawcze z nagraniami audio lub wideo oraz opcjami podkładu, metronomu i tempa; zgłoszenia grupowe do wspólnego pisania; instrukcje w formacie rich text; podgrupy uczniów; zaplanowane i indywidualnie kierowane zadania Microsoft Teams; rozbudowane opisy i typy zadań w bibliotece zasobów.
• Ujednolicona konfiguracja LTI dla LTI 1.1 i 1.3, w tym rejestracja dynamiczna. Poprzednie wywołania poświadczeń LTI 1.1 są przestarzałe.
• Roczne statystyki partytur, liczba publicznych partytur na profilach oraz usunięcie kilku pól wycofywanych od dawna.

• Dodano metody getMP3 i getWAV do eksportu dźwięku
• Dodano zdarzenie exportProgress, dzięki czemu przy dłuższym eksporcie można wyświetlić postęp

• Listy partytur użytkownika to profile publiczne. Pobieranie listy partytur użytkownika zwraca teraz tylko jego publiczne partytury, z nową paginacją i sortowaniem — zgodnie ze zmianą zapowiedzianą w 2020 roku.
• Szczegóły partytury ujawniają adres URL edycji, nazwy instrumentów i ewentualną zaplanowaną datę usunięcia; kolekcje podają liczbę partytur; profile publiczne pokazują liczbę polubień i odtworzeń.
• Flat for Education. Filtruj bibliotekę zasobów według typu zadania, przedmiotu i poziomu klasy; zasoby zawierają opis udostępniania i opcje prywatności; zadania mogą ograniczać odtwarzanie nut i ścieżki audio; przesłania obsługują usługi ocen LTI 1.1 i 1.3.

• Stronicowane polubienia na profilach użytkowników oraz produkt, z którego użytkownik korzysta, w szczegółach konta.
• Uprawnienia zasobów informują, czy wywołujący jest właścicielem, współpracownikiem użytkownika czy współpracownikiem grupy, wraz z datą dodania każdego współpracownika. Szczegóły partytury obejmują teraz główną tonację, datę wyróżnienia i organizację.
• Flat for Education. Zaproszenia mogą być używane wielokrotnie; zgłoszenia zyskują status ocenionych oraz szczegóły odtwarzania i LTI; zadanie można skopiować do biblioteki zasobów tylko wtedy, gdy jeszcze się w niej nie znajduje; organizacje otrzymują własne biblioteki zasobów z poziomem prywatności dla całej organizacji.

Odczytuj strukturę załadowanej partytury bezpośrednio ze swojego kodu.

• Partie i głosy: getNbParts, getPartsUuids, getMeasureVoicesUuids
• Nuty: getMeasureNbNotes, getNoteData, playbackPositionToNoteIdx
• Nowy parametr URL noAudio wyłącza odtwarzanie dźwięku
• Naprawiono błąd, przez który setMasterVolume wywoływało niewłaściwą metodę wewnętrzną

• Usunięto obsługę jQuery w konstruktorze — zamiast tego przekaż element DOM lub jego identyfikator
• Opublikowany moduł npm zawiera typy TypeScript
• Oddzielne kompilacje ES i UMD

• Twórz linki LTI z elementów biblioteki zasobów Flat for Education, aby umieszczać je bezpośrednio w kursie LMS.
• Maksymalna liczba punktów za zadanie wzrasta ze 100 do 10 000.
• Metadane partytury (podtytuł, kompozytor, autor tekstu, aranżer, opis, licencja…) można teraz również wyczyścić przez API, a nie tylko ustawić.

• Resource Library API (beta). Przeglądaj biblioteki zasobów Flat for Education i zarządzaj nimi dzięki dwóm nowym zakresom OAuth2: pełnemu dostępowi oraz dostępowi tylko do odczytu. Zadania można kopiować do biblioteki zasobów.
• Konta testowe uczniów. Twórz testowe konta uczniów w klasie, aby sprawdzać zadania tak, jak widzi je uczeń.
• Zadania informują, co można z nimi zrobić (edytować, publikować, archiwizować…), czy ich załączniki są dedykowanymi kopiami oraz o wszelkich napotkanych problemach. Historia oddań zapisuje źródło zmiany, gdy pochodzi ona z Google Classroom, Microsoft Teams lub LMS.
• Zresetowanie oddania pozostawia je na miejscu zamiast je usuwać; udostępniane są metadane klasy (poziom, umiejętności, liczebność) oraz szczegóły logowania Microsoft na kontach.
• Wersje partytury zwracają swoje daty rozpoczęcia i zakończenia; kreatory partytur mogą włączać ćwierćtony; kopie mogą zachować oryginalny tytuł.

• Takty: getNbMeasures, getMeasuresUuids
• Nawigacja: goLeft, goRight, scrollToCursor
• Metronom: getMetronomeMode, setMetronomeMode
• Tempo odtwarzania: getPlaybackSpeed, setPlaybackSpeed

• Linki logowania i delegowane tokeny dostępu. Administratorzy Flat for Education mogą utworzyć link logowania dla dowolnego użytkownika w swojej organizacji albo token dostępu działający w imieniu tego użytkownika: to podstawa niestandardowych portali i integracji z logowaniem jednokrotnym.
• Japoński w hiraganie (ja-HIRA) dołącza do obsługiwanych ustawień regionalnych; komentarze publiczne pokazują swój stan moderacji.
• Eksporty audio zwracają zestaw MP3 jako domyślną ścieżkę, jeśli jest dostępny. Usunięto opcję żądania wyłącznie eksportów z pamięci podręcznej, ponieważ eksporty audio są teraz zawsze serwowane z pamięci podręcznej.

• Kreator partytury. Utwórz pustą partyturę bez importowania pliku MusicXML: podaj listę instrumentów oraz opcjonalnie metrum, oznaczenie tonacji, tabulaturę, diagramy akordów i układ strony.
• Flat for Education. Użytkowników organizacji można tworzyć z rolą; arkusze ćwiczeń mogą losowo zmieniać kolejność swoich zadań; zgłoszenia uczniów zawierają listę ćwiczeń, które obejmują.

• Ścieżki odtwarzania. Wyświetlaj ścieżki generowane i automatycznie synchronizowane przez Flat (odtwarzanie jako MP3), pobieraj punkty synchronizacji najnowszego pliku odtwarzania i otrzymuj adres URL CDN eksportu w treści odpowiedzi.
• Flat for Education. Nauczyciele mogą resetować pracę ucznia; klasy zgłaszają konta, których nie udało się dodać podczas synchronizacji; zadania i prace udostępniają swój stan oraz linki Microsoft Teams; kopie zadań można planować; zgłoszenia wykonań zawierają zapisaną ścieżkę audio.
• Profile zyskują zdjęcie w tle, a identyfikator bieżącego użytkownika można pobrać osobno.

• loadFlatScore akceptuje sharingKey, dzięki czemu można wczytać prywatnie udostępnioną partyturę
• Dodano setTrack, useTrack i seekTrackTo, aby dynamicznie ustawiać ścieżkę audio

• Eksport ocen. Pobierz oceny zadania jako plik CSV lub Excel.
• Zadania mają teraz swój typ i obraz okładki; kopiowanie zadania może nadpisać istniejący szkic treścią innego zadania.
• Przy współpracownikach widać, czy ich zaproszenie nadal oczekuje na akceptację.

• Ocenianie przez API. Ustawiaj oceny robocze i końcowe, odsyłaj przesłanie uczniowi i odczytuj wyliczane liczniki komentarzy; maksymalna liczba punktów jest zapisywana razem z oceną.
• Komentarze do przesłania. Twórz, wyświetlaj, aktualizuj i usuwaj komentarze do przesłania.
• Opcje zadania. Zestawy narzędzi, limit odtwarzania, maksymalna liczba punktów, tematy Google Classroom, przypisywanie konkretnym uczniom, zablokowane szablony oraz szczegóły zadań LTI, Canvas i MusicFirst.
• Administratorzy mogą edytować nazwę użytkownika, imię i nazwisko oraz adres e-mail konta zarządzanego; listy użytkowników można filtrować według aktywnej licencji.
• Stare parametry przesłania studentComment i returnFeedback zostały usunięte na rzecz nowych wywołań oceniania.

• Archiwizuj i przywracaj zadania z archiwum oraz odczytuj główny typ zadania (nowa partytura, szablon lub współdzielone pisanie).
• Użytkownicy organizacji. Twórz konta z imieniem i nazwiskiem, sortuj i filtruj listy użytkowników, zliczaj użytkowników pasujących do filtra oraz filtruj członków grup według źródła synchronizacji (Google Classroom, Microsoft Teams, Clever).
• Szczegóły partytury zawierają listę sampli audio używanych do odtwarzania oraz znormalizowaną listę instrumentów, która nie zależy już od sampli.

Steruj miksem z poziomu swojego kodu i odczytuj, co znajduje się pod kursorem.

• Głośność i wyciszanie: getMasterVolume, setMasterVolume, getPartVolume, setPartVolume, mutePart, unmutePart
• Solo i pogłos: setPartSoloMode, unsetPartSoloMode, getPartSoloMode, getPartReverb, setPartReverb
• Inspekcja: getMeasureDetails, getNoteDetails
• Dodane zdarzenia: noteDetails, measureDetails, cursorContext

• Specyfikacja przechodzi na OpenAPI 3.0. Poprzednie wersje były opisane w OpenAPI 2 (Swagger).
• Partytury udostępniają informacje o aranżerze i statystyki odtworzeń; usunięcie można zaplanować tak, aby zostało wykonane wkrótce, zamiast pozostawać w koszu.
• Flat for Education. Załączniki do zadań mogą być plikami z Google Drive, klasy zawierają informacje o Microsoft Teams, a konta edukacyjne udostępniają imię i nazwisko.

• Zmiany metadanych od razu trafiają do edytora. Gdy zaktualizujesz przez API tytuł utworu, podtytuł, kompozytora, autora tekstu lub treść licencji, zmiany są wysyłane do otwartych edytorów w czasie rzeczywistym i zapisywana jest nowa wersja. Opisy mogą być dwa razy dłuższe (2,000 znaków).
• Zadania oddawane w Education udostępniają swój stan (utworzone, oddane, zwrócone); metadane rewizji zwracają ostatnie zdarzenie modyfikacji.
• Turecki dołącza do obsługiwanych języków; profile publiczne informują, czy konto należy do zespołu Flat.

• Dodano getMIDI
• getMusicXML zwraca teraz Uint8Array na najwyższym poziomie — odpowiedź nie zawiera już właściwości .data
• voiceIdx kursora nosi teraz nazwę voiceIdxInStaff

Zaktualizowano pod kątem wydania embed.

• SDK jest teraz domyślnie ładowane z flat-embed.com
• Usunięto przestarzałą akcję edit i zdarzenie edit
• Usunięto setNoteColor

• Więcej formatów importu. Można importować pliki Guitar Pro (GP3, GP4, GP5, GPX, GP), PowerTab, TuxGuitar i MuseScore, a import akceptuje nazwę pliku.
• Kolekcje można wyświetlać w ramach kolekcji nadrzędnej i zwracają one datę utworzenia; partytury podają kolekcje, do których należą.
• Komentarze kontekstowe są zakotwiczane do pięciolinii za pomocą identyfikatora zamiast indeksu, a uprawnienia zasobu wskazują, czy wywołujący jest współpracownikiem.

• API kolekcji. Twórz, wyświetlaj, aktualizuj, usuwaj i przywracaj kolekcje, wyświetlaj ich partytury oraz dodawaj i usuwaj partytury, z trzema nowymi zakresami OAuth2: tylko do odczytu, tylko do dodawania i pełny dostęp.
• Partytury można przywracać z kosza; usunięcie partytury bez uprawnień administratora powoduje zamiast tego cofnięcie jej udostępnienia na Twoim koncie; kopię można zapisać w konkretnej kolekcji.
• Komentarze można filtrować według typu (dokumentowe lub osadzone).
• Eksport głosów używa teraz identyfikatorów głosów zamiast indeksów, a od września 2019 lista partytur użytkownika zwraca tylko partytury publiczne.

• Zarządzanie kontami organizacji. Administratorzy mogą aktualizować zarządzane konta, usuwać je lub przekształcać w konta indywidualne; listy użytkowników i zaproszeń korzystają z paginacji opartej na kursorach.
• Klasy zyskują stan nieaktywny, który można ponownie aktywować, a także zwracają domenę Canvas LMS i sekcję Clever; zadania zyskują stan wersji roboczej oraz typ załącznika ćwiczenia.
• Profile udostępniają motyw i informacje o instrumentach, na których gra użytkownik.

• Dodano metodę focusScore, aby ustawić fokus klawiatury na osadzeniu
• Nowa właściwość defaultMode w konfiguracji edytora

• Pierwsze API edukacyjne są publicznie dostępne. Zarządzaj klasami, zadaniami i przesłaniami, kontami organizacji i zaproszeniami, poświadczeniami LTI oraz grupami i użytkownikami organizacji: wszystkim, czego potrzebuje integracja szkolna.
• Dostęp o określonym zakresie. Nowe zakresy OAuth2 obejmują klasy, zadania i administrację organizacją, każdy także w wariancie tylko do odczytu, dzięki czemu integracja prosi tylko o to, czego potrzebuje.

Twój kod może teraz sprawdzać, jak skonfigurowane jest osadzenie, i przełączyć je w tryb edytora.

• Dodano metody: getEmbedConfig, setEditorConfig, edit
• Dodano zdarzenie: edit

SDK potrafi teraz wczytywać partytury z MusicXML i zgłaszać działania czytnika.

• Dodano metody: getAutoZoom, setAutoZoom, loadMusicXML, getMusicXML
• Dodano zdarzenia: scoreLoaded, cursorPosition, rangeSelection, pause, stop, fullscreen, print
• Dodano testy integracyjne

Pierwsze publiczne wydanie interfejsu Flat REST API. Odczytuj i zarządzaj swoim kontem, partyturami, użytkownikami i grupami z własnych aplikacji i skryptów, korzystając z OAuth2, aby działać w imieniu innych użytkowników Flat.

Wszystkie późniejsze zmiany są opisane w dzienniku zmian API, a dokumentacja dla deweloperów obejmuje uwierzytelnianie, dokumentację referencyjną i przewodniki.