Developer changelog

開發者儀表板已依照你的整合可執行的功能重新打造。每項功能（Embed、OMR、REST API、Import API、LTI）都有一張卡片，顯示其範圍、定價與文件，而你的應用程式已在使用的功能會優先顯示。

• 帳戶層級新增 OMR 區塊，可在同一處查看你的工作、點數及其歷程，因為 OMR 點數是由你所有應用程式共用。
• 寫程式前先試用 OMR。 測試沙盒可接受 PDF 或照片，顯示頁數、每頁費用，以及執行後剩餘的點數餘額，待你確認後再執行工作。輸出會提供為 MusicXML 下載，不會存入你的資料庫。
• 更清楚的應用程式頁面。 Personal tokens、OAuth2 憑證與 OMR 存取權限會依應用程式分組顯示，並特別標示具備 OMR scope 的憑證。

可從 flat.io/developers 開啟。

我們的 REST API 規格升級到 OpenAPI 3.1，OMR API 結束 beta 階段，Flat for Education 的作業功能也不再只限於列出與建立。

• OMR API 已穩定。 端點、欄位與行為在任何破壞性變更前，現在都會遵循我們一貫的淘汰程序。新的 FAQ 說明了點數與計費、限制與處理時間、辨識品質與語言，以及商業用途與隱私。
• 在 Flat for Education 中可讀取、更新與刪除作業。刪除作業也會一併移除其提交內容與學生的副本；若要保留作業內容，請改為封存。
• 點數分類帳。 新增呼叫可列出你的點數歷史；餘額仍保留在 OMR capabilities 呼叫中。
• 支援匯入 Finale 檔案（.musx），以 best-effort 為原則，且建立樂譜時也已記錄掃描樂譜匯入（PDF 與圖片）的相關說明。
• OpenAPI 3.1。 可為 null 的欄位現在使用 3.1 語法；工具若固定使用 OpenAPI 3.0，則需要更新。OMR 檔案上傳中的 mimeType 欄位已移除。

• 由你控制資料保留期限。 OMR 工作現在會告訴你其檔案會保留多久（預設為 30 天），每個 MusicXML 工作都會附帶其到期日，而且你可以在收集完成後立即刪除工作檔案與結果。
• 登入前即可偵測功能。 OMR capabilities 呼叫現在無須帳號即可使用，並會列出支援的辨識語言及其名稱。
• ABC 記譜匯出 現已支援任何樂譜修訂版本，與 MusicXML、MIDI 和其他格式並列。和 MIDI 一樣，它不包含完整的排版資訊。
• 在 Flat for Education 中，Free Record assignments 現在可透過 API 進行設定。
• 來自上游提供者（例如 Google Classroom）的錯誤，現在會附帶該提供者自己的本地化訊息。

Flat 的 OMR 引擎現在可透過開發者 API以程式方式使用。你可以傳送 PDF 或照片、追蹤辨識進度、檢視偵測到的樂器，然後將結果匯入 Flat 資料庫作為可編輯的樂譜，或匯出為 MusicXML 或 MIDI。這與編輯器中 PDF 與照片匯入所使用的是同一套內部模型，現在也能大規模用於你自己的應用程式與工作流程。

專用的 OMR API（v2.24.0）是建立在 v2.23.0 新增至樂譜建立流程的背景 PDF 匯入功能之上：匯入檔案時可要求任務支援，並輪詢該任務直到樂譜準備完成。兩個版本的詳細內容，請參閱 API 變更日誌。

自 2024 年以來最大的一次規格更新，讓 API 跟上過去兩年的產品變更。

• 支援從 15+ 種格式匯入。 Guitar Pro、MuseScore、ABC 記譜、PowerTab、Capella、MEI、Overture、TablEdit、Band-in-a-Box、Karaoke MIDI、MuseData、Score Writer、Bagpipe Music Writer 和 Encore 現已加入 MusicXML 與 MIDI 的行列，樂譜也可匯出為原生 .flat 檔案。
• 虛擬收藏。 所有樂譜、協作內容與按讚項目將取代資料庫中舊有的資料夾階層，與重新設計的 Flat 資料庫保持一致。
• Flat for Education。 支援含音訊或視訊錄製的演奏作業，以及伴奏音軌、節拍器與速度選項；支援共同創作的小組繳交；支援富文字說明；學生子群組；可排程並指定給個別對象的 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 建置

• 可從 Flat for Education 資源庫項目建立 LTI 連結，以便直接放入 LMS 課程中。
• 作業的最高成績已從 100 分提高到 10,000 分。
• 現在可透過 API 清除樂譜中繼資料（副標題、作曲者、作詞者、編曲者、描述、授權等），而不再只能設定。

• Resource Library API（beta）。 可瀏覽並管理 Flat for Education 的資源庫，並提供兩個新的 OAuth2 scope，分別用於完整存取與唯讀存取。作業也可以複製到資源庫中。
• 測試學生。 可在班級中建立測試用學生帳號，以學生身分試做作業。
• 作業現在會回報你可對其執行的操作（編輯、發佈、封存等）、其附件是否為專用副本，以及遇到的任何問題。提交記錄歷史現在也會記錄變更來源，例如來自 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 播放），擷取最新播放檔案的同步點，並在回應本文中取得匯出的 CDN URL。
• 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 字元）。
• 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 檔案，且匯入時可接受檔案名稱。
• 集合現在可列在父集合之下，並回報其建立日期；樂譜會列出自己所屬的集合。
• 情境註解現在會以識別碼而非索引錨定到譜表，且資源權限會指出呼叫端是否為協作者。

• Collections API。 可建立、列出、更新、刪除與還原收藏集、列出其中的樂譜，以及新增或移除樂譜，並提供 3 個新的 OAuth2 權限範圍，分別對應唯讀、僅可新增與完整存取。
• 樂譜現在可從垃圾桶還原；在沒有管理員權限時刪除樂譜，會改為將該樂譜自你的帳號取消分享；另外，複本可指定儲存到特定收藏集。
• 留言現在可依類型篩選（文件或行內）。
• 聲部匯出現在使用聲部識別碼而非索引，且自 2019 年 9 月起，使用者的樂譜列表只會回傳公開樂譜。

• 組織帳戶管理。 管理員現在可以更新受管理帳戶，並將其刪除或轉換為一般使用者帳戶；使用者與邀請清單改用游標式分頁。
• 班級新增非啟用狀態，之後可重新啟用，並會回報其 Canvas LMS 網域與 Clever 班級區段；作業新增草稿狀態，以及練習附件類型。
• 個人資料現在會顯示主題與所演奏的樂器。

• 新增 focusScore 方法，讓嵌入的樂譜取得鍵盤焦點
• 在編輯器設定中新增 defaultMode 屬性

• 首批教育 API 已公開。 可管理班級、作業與提交內容、組織帳戶與邀請、LTI 憑證，以及組織的群組與使用者：學校整合所需的一切功能。
• 範圍限定的存取權。 全新的 OAuth2 scopes 涵蓋班級、作業與組織管理，且各自提供唯讀版本，讓整合只需請求其真正需要的權限。

現在，您的程式碼可以檢查嵌入內容的設定方式，並將其切換為編輯器。

• 新增方法：getEmbedConfig、setEditorConfig、edit
• 新增事件：edit

SDK 現在可以從 MusicXML 載入樂譜，並回報讀譜器目前的操作。

• 新增方法：getAutoZoom、setAutoZoom、loadMusicXML、getMusicXML
• 新增事件：scoreLoaded、cursorPosition、rangeSelection、pause、stop、fullscreen、print
• 新增整合測試

Flat REST API 的首次公開發佈。你可以透過自己的應用程式和指令碼讀取及管理帳戶、樂譜、使用者與群組，並使用 OAuth2 代表其他 Flat 使用者執行操作。

此後的所有更新都記錄於 API 變更記錄，而開發人員文件則涵蓋驗證、API 參考資料與指南。