開發者更新日誌

開發者儀表板已按你的整合功能重新設計。每項功能（Embed、OMR、REST API、Import API、LTI）現在都有一張卡片，顯示其範圍、收費和文件，而你的應用程式已在使用的功能會排在前面。

• 新增帳戶層級的 OMR 區段，將你的工作、額度及其記錄集中在同一處，因為 OMR 額度由你所有應用程式共用。
• 寫程式碼前先試用 OMR。 playground 可接收 PDF 或相片，顯示頁數、每頁費用，以及執行後會剩下多少餘額；待你確認後才會執行工作。輸出只會提供 MusicXML 下載，不會存入你的資料庫。
• 更清晰的應用程式頁面。 個人 token、OAuth2 憑證和 OMR 存取權會按應用程式分組，並清楚標示帶有 OMR scope 的憑證。

可從 flat.io/developers 開啟。

我們的 REST API 規格已遷移至 OpenAPI 3.1，OMR API 結束測試期，而 Flat for Education 的作業功能也不再只限於列出與建立。

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

• 資料保留時間由你控制。 OMR 工作現在會告知其檔案會保留多久（預設為 30 天），每個 MusicXML 工作都會附帶其到期日期，而你亦可在取回工作檔案和結果後立即將其刪除。
• 登入前即可偵測功能。 OMR capabilities 呼叫現在無需帳戶即可使用，並會列出支援的辨識語言及其名稱。
• 支援匯出 ABC 記譜，適用於任何樂譜修訂版本，與 MusicXML、MIDI 及其他格式一同提供。與 MIDI 一樣，它不包含完整的排版資訊。
• 在 Flat for Education 中，Free Record 作業現在可以透過 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 notation、PowerTab、Capella、MEI、Overture、TablEdit、Band-in-a-Box、Karaoke MIDI、MuseData、Score Writer、Bagpipe Music Writer 和 Encore 現已加入 MusicXML 與 MIDI 的支援行列，樂譜亦可匯出為原生 .flat 檔案。
• 虛擬集合。 All scores、collaborations 與 likes 取代了資料庫中舊有的資料夾階層，與重新設計的 Flat 資料庫一致。
• Flat for Education。 支援附有音訊或影片錄製的演奏作業，以及 backing track、metronome 和 speed 選項；用於共同寫作的小組提交；富文字指示；學生子分組；可排程並針對個別學生指派的 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 建置

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

• Resource Library API（測試版）。 透過兩個新的 OAuth2 權限範圍（完整存取及唯讀存取），瀏覽及管理 Flat for Education 資源庫。作業可複製到資源庫。
• 測試學生。 在班級中建立測試學生帳戶，以學生身分試用作業。
• 作業現在會說明你可對其執行的操作（編輯、發佈、封存等）、其附件是否為專用副本，以及遇到的任何問題。提交歷程會記錄變更來源，例如來自 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 characters）。
• Flat for 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 scope，分別用於唯讀、只可新增及完整存取。
• 樂譜現在可以從垃圾桶還原；如果在沒有管理員權限的情況下刪除樂譜，系統會改為取消該樂譜與你帳戶的分享；複製副本時亦可指定目標收藏集。
• 評論現在可以按類型篩選（文件評論或行內評論）。
• 聲部匯出現在使用聲部識別碼而不是索引；並且由 2019 年 9 月起，使用者的樂譜列表只會傳回公開樂譜。

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

• 新增 focusScore 方法，用於將鍵盤焦點設到嵌入的樂譜上
• 在編輯器設定中新增 defaultMode 屬性

• 首批教育 API 現已公開。 你現在可以管理班級、作業和提交、機構帳戶和邀請、LTI 憑證，以及機構中的群組和使用者：學校整合所需的一切功能都已具備。
• 範圍化存取。 新增的 OAuth2 scope 涵蓋班級、作業及機構管理，且每項都提供唯讀版本，因此整合只需請求其所需的權限。

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

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

SDK 現已支援從 MusicXML 載入樂譜，並回報閱讀器正在執行的操作。

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

這是 Flat REST API 的首個公開版本。你可以透過自己的應用程式和腳本讀取及管理帳戶、樂譜、使用者和群組，並使用 OAuth2 代表其他 Flat 使用者執行操作。

此後的所有更新都記錄於 API 更新日誌，而開發者文件則涵蓋驗證、參考資料和指南。