开发者更新日志

Flat 现已在 https://mcp.flat.io/mcp 提供远程 Model Context Protocol 服务器，让任何 MCP 客户端都能使用用户 Flat 账户中的乐谱。

• 首批提供四个工具：search、score_get、score_export（MusicXML、压缩 MusicXML、MIDI）和 score_create（MusicXML、MIDI、ABC、MuseScore、Guitar Pro）。现有乐谱绝不会被修改、删除或设为公开。
• 采用 OAuth 2.1 和 PKCE，仅使用 mcp 这一权限范围，通过 Client ID Metadata Documents 或 Dynamic Client Registration 注册客户端。无需 API 密钥：用户在 Flat 的授权页面上批准每个客户端的访问请求。
• 兼容 Claude Code、Codex、Gemini CLI、Cursor 和 VS Code，只需一条命令或一项配置即可连接。

连接的账户须有有效的 Flat Power 订阅。首个版本支持读取和创建乐谱；我们将根据您发送至 developers@flat.io 的反馈添加工具。

完整指南：Flat MCP 服务器。

开发者控制台已围绕你的集成能力重新设计。每项能力（Embed、OMR、REST API、Import API、LTI）现在都有一张卡片，显示其作用范围、价格和文档，而你的应用已在使用的能力会排在前面。

• 新增账户级 OMR 部分，将你的任务、额度及其历史记录集中在一处，因为 OMR 额度由你的所有应用共享。
• 写代码前先试用 OMR。 playground 可接收 PDF 或照片，显示页数、每页费用以及执行后剩余的余额；确认后才会运行任务。输出仅提供 MusicXML 下载，不会进入你的资料库。
• 更清晰的应用页面。 个人令牌、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 更新日志 中，开发者文档则涵盖了身份验证、参考文档和指南。