개발자 변경 로그

이제 Flat은 https://mcp.flat.io/mcp에서 원격 Model Context Protocol 서버를 운영합니다. 모든 MCP 클라이언트에서 고객의 Flat 계정에 있는 악보를 다룰 수 있습니다.

• 초기 제공 도구 4개: search, score_get, score_export(MusicXML, 압축 MusicXML, MIDI), score_create(MusicXML, MIDI, ABC, MuseScore, Guitar Pro). 기존 악보는 수정, 삭제되거나 공개로 전환되지 않습니다.
• PKCE를 사용하는 OAuth 2.1, 단일 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을 시험해 볼 수 있습니다. 플레이그라운드에 PDF 또는 사진을 넣으면 페이지 수, 페이지당 비용, 실행 후 남게 될 잔액을 보여주고, 확인하면 작업을 실행합니다. 출력은 MusicXML 다운로드로 제공되며 라이브러리에는 추가되지 않습니다.
• 더 명확해진 앱 페이지. 개인 토큰, OAuth2 자격 증명, OMR 접근 권한이 애플리케이션별로 묶여 표시되며, OMR 범위를 포함한 자격 증명도 분명하게 구분됩니다.

flat.io/developers에서 열 수 있습니다.

REST API 사양이 OpenAPI 3.1로 옮겨가고, OMR API는 베타 기간을 마쳤으며, Flat for Education 과제는 목록 조회와 생성만 넘어서 더 많은 작업을 지원합니다.

• OMR API가 안정화되었습니다. 이제 엔드포인트, 필드, 동작은 호환성이 깨지는 변경 전에 당사의 일반적인 지원 중단 절차를 따릅니다. 새 FAQ에는 크레딧과 청구, 한도와 처리 시간, 인식 품질과 언어, 상업적 사용과 개인정보 보호가 정리되어 있습니다.
• Flat for Education에서 과제를 조회, 수정, 삭제할 수 있습니다. 과제를 삭제하면 제출물과 학생 사본도 함께 삭제되므로, 작업을 보관하려면 삭제 대신 보관 처리하세요.
• 크레딧 원장. 새 호출로 크레딧 사용 내역을 조회할 수 있으며, 잔액은 계속 OMR capabilities 호출에서 확인할 수 있습니다.
• Finale 파일 (.musx) 가져오기를 지원합니다. 다만 가능한 범위 내에서 처리되며, 스캔한 악보 가져오기(PDF 및 이미지)는 스코어 생성 문서에 추가되었습니다.
• OpenAPI 3.1. nullable 필드는 3.1 문법을 사용합니다. OpenAPI 3.0에 고정된 도구는 업데이트가 필요합니다. mimeType 필드는 OMR 파일 업로드에서 제거되었습니다.

• 직접 제어하는 데이터 보관. 이제 OMR 작업에서 파일이 얼마나 오래 보관되는지 알려 주며(기본값은 30 days), 각 MusicXML 작업에는 만료일이 포함되고, 수집이 끝나는 즉시 작업의 파일과 결과를 삭제할 수 있습니다.
• 로그인 전 기능 확인. OMR 기능 호출은 계정 없이도 작동하며, 지원되는 인식 언어를 이름과 함께 나열합니다.
• 모든 악보 리비전에 대해 ABC 기보법 내보내기를 지원하며, MusicXML, MIDI 및 다른 형식과 함께 사용할 수 있습니다. MIDI와 마찬가지로 전체 조판 정보는 포함되지 않습니다.
• Flat for Education에서 Free Record 과제를 API로 구성할 수 있습니다.
• 이제 업스트림 제공업체(예: Google Classroom)에서 오는 오류에는 해당 제공업체의 현지화된 자체 메시지도 포함됩니다.

이제 Flat의 OMR 엔진을 developer API를 통해 프로그래밍 방식으로 사용할 수 있습니다. PDF나 사진을 전송하고, 인식 진행 상황을 추적하고, 감지된 악기를 검토한 다음, 결과를 Flat 라이브러리의 편집 가능한 악보로 가져오거나 MusicXML 또는 MIDI로 내보낼 수 있습니다. 이는 에디터에서 PDF 및 사진 가져오기를 지원하는 동일한 자체 개발 모델로, 이제 여러분의 앱과 워크플로 전반에서 규모 있게 사용할 수 있습니다.

전용 OMR API(v2.24.0)는 v2.23.0에서 악보 생성에 추가된 백그라운드 PDF 가져오기를 기반으로 합니다. 파일을 가져올 때 작업 지원을 요청하고, 악보가 준비될 때까지 해당 작업을 폴링하면 됩니다. 두 릴리스의 자세한 내용은 API 변경 기록에서 확인하세요.

2024년 이후 가장 큰 규모의 사양 업데이트로, 지난 2년간의 제품 변경 사항에 맞춰 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 1.1 및 1.3용 통합 LTI 구성으로 동적 등록을 지원합니다. 이전 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(베타). Flat for Education 리소스 라이브러리를 탐색하고 관리할 수 있으며, 전체 액세스와 읽기 전용 액세스를 위한 새로운 OAuth2 스코프 2개가 추가되었습니다. 과제는 리소스 라이브러리로 복사할 수 있습니다.
• 테스트 학생. 클래스에서 테스트용 학생 계정을 만들어 학생의 입장에서 과제를 시험해 볼 수 있습니다.
• 과제는 수행할 수 있는 작업(편집, 게시, 보관 등), 첨부 파일이 전용 사본인지 여부, 발생한 문제를 알려줍니다. 제출 기록에는 Google Classroom, Microsoft Teams 또는 LMS에서 변경이 이루어진 경우 그 변경의 출처가 기록됩니다.
• 제출물을 재설정해도 삭제되지 않고 그대로 유지됩니다. 클래스 메타데이터(수준, 기술, 규모)와 계정의 Microsoft 로그인 정보도 제공됩니다.
• 악보 리비전은 시작일과 종료일을 반환합니다. 악보 빌더에서는 사분음표가 아니라 4분음을 활성화할 수 있으며, 사본은 원래 제목을 유지할 수 있습니다.

• 마디: 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 정보가 포함되며, Education 계정에서는 이름과 성을 확인할 수 있습니다.

• 메타데이터 수정 내용이 편집기에 실시간으로 반영됩니다. API를 통해 악보의 제목, 부제, 작곡가, 작사가 또는 라이선스 텍스트를 업데이트하면, 변경 사항이 열려 있는 편집기에 실시간으로 전송되고 새 버전이 저장됩니다. 설명은 두 배 길이인 2,000자까지 작성할 수 있습니다.
• Education 제출물은 상태(created, turned in, returned)를 표시하며, 리비전 메타데이터는 마지막 수정 이벤트를 반환합니다.
• 지원 로케일에 터키어가 추가되었으며, 공개 프로필에는 계정이 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 속성 추가

• 첫 번째 Education API가 공개되었습니다. 수업, 과제 및 제출물, 조직 계정과 초대, LTI 자격 증명, 그리고 조직의 그룹과 사용자를 관리할 수 있어 학교 연동에 필요한 기능을 모두 제공합니다.
• 범위가 지정된 액세스. 새로운 OAuth2 스코프는 수업, 과제, 조직 관리를 지원하며, 각각 읽기 전용 변형도 제공하므로 연동은 필요한 권한만 요청하면 됩니다.

이제 코드에서 임베드가 어떻게 구성되어 있는지 확인하고 이를 편집기로 전환할 수 있습니다.

• 추가된 메서드: getEmbedConfig, setEditorConfig, edit
• 추가된 이벤트: edit

이제 SDK가 MusicXML에서 악보를 불러오고, 리더에서 어떤 동작이 일어나고 있는지 알려줄 수 있습니다.

• 추가된 메서드: getAutoZoom, setAutoZoom, loadMusicXML, getMusicXML
• 추가된 이벤트: scoreLoaded, cursorPosition, rangeSelection, pause, stop, fullscreen, print
• 통합 테스트 추가

Flat REST API의 첫 공개 릴리스입니다. OAuth2를 사용해 다른 Flat 사용자를 대신하여 작업하면서, 자체 앱과 스크립트에서 계정, 악보, 사용자, 그룹을 읽고 관리할 수 있습니다.

이후의 모든 변경 사항은 API 변경 로그에 기록되어 있으며, 개발자 문서에서는 인증, 레퍼런스, 가이드를 다룹니다.