Registro de alterações para desenvolvedores

O painel de desenvolvedor foi reformulado com base no que sua integração pode fazer. Cada recurso (Embed, OMR, REST API, Import API, LTI) tem um cartão com seu escopo, preços e documentação, e os que seu app já usa aparecem primeiro.

• Uma nova seção de OMR no nível da conta, com suas tarefas, seus créditos e o histórico deles em um só lugar, já que os créditos de OMR são compartilhados por todos os seus apps.
• Experimente OMR antes de escrever código. O playground aceita um PDF ou fotos, mostra a quantidade de páginas, o custo por página e o saldo que restaria, e então executa a tarefa depois da sua confirmação. A saída vai para downloads em MusicXML, nada é enviado para a sua biblioteca.
• Páginas de app mais claras. Tokens pessoais, credenciais OAuth2 e acesso ao OMR ficam agrupados por aplicação, com destaque para as credenciais que incluem o escopo de OMR.

Abra em flat.io/developers.

Nossa especificação da REST API passa para OpenAPI 3.1, a API OMR encerra seu período beta, e as tarefas do Flat for Education passam a ir além de listagem e criação.

• A API OMR está estável. Endpoints, campos e comportamento agora seguem nosso processo usual de descontinuação antes de qualquer mudança incompatível. Um novo FAQ cobre créditos e cobrança, limites e tempos de processamento, qualidade de reconhecimento e idiomas, além de uso comercial e privacidade.
• Leia, atualize e exclua tarefas no Flat for Education. Excluir uma tarefa também remove seus envios e as cópias dos alunos; em vez disso, arquive-a para manter o trabalho.
• Extrato de créditos. Uma nova chamada lista seu histórico de créditos; o saldo continua na chamada de recursos do OMR.
• Arquivos Finale (.musx) podem ser importados, em regime de melhor esforço, e a importação de música digitalizada (PDF e imagens) está documentada na criação de partituras.
• OpenAPI 3.1. Campos nullable usam a sintaxe 3.1; ferramentas fixadas em OpenAPI 3.0 precisam de atualização. O campo mimeType foi removido dos uploads de arquivos OMR.

• Retenção de dados sob seu controle. Os trabalhos OMR agora informam por quanto tempo seus arquivos são mantidos (30 dias por padrão), cada trabalho MusicXML inclui sua data de expiração, e você pode apagar os arquivos e resultados de um trabalho assim que coletá-los.
• Detecção de recursos antes do login. A chamada de capacidades do OMR funciona sem uma conta e lista os idiomas de reconhecimento compatíveis com seus nomes.
• Exportação de notação ABC para qualquer revisão da partitura, junto com MusicXML, MIDI e os outros formatos. Assim como o MIDI, ela não inclui toda a gravação tipográfica.
• Tarefas Free Record podem ser configuradas pela API no Flat for Education.
• Erros vindos de um provedor upstream (como o Google Classroom, por exemplo) agora incluem a própria mensagem localizada do provedor.

O mecanismo de OMR do Flat agora está disponível programaticamente por meio da API para desenvolvedores. Envie PDFs ou fotos, acompanhe o progresso do reconhecimento, revise os instrumentos detectados e depois importe o resultado como uma partitura editável em uma biblioteca do Flat ou exporte em MusicXML ou MIDI. É o mesmo modelo interno que viabiliza a importação de PDFs e fotos no editor, agora disponível em escala para seus próprios apps e fluxos de trabalho.

A API dedicada de OMR (v2.24.0) se baseia na importação de PDFs em segundo plano adicionada à criação de partituras na v2.23.0: solicite suporte a tarefas ao importar um arquivo e faça polling da tarefa até que a partitura esteja pronta. Consulte o changelog da API para ver os detalhes de ambas as versões.

A maior atualização da especificação desde 2024, colocando a API em dia com dois anos de mudanças no produto.

• Importação de mais de 15 formatos. Guitar Pro, MuseScore, notação ABC, PowerTab, Capella, MEI, Overture, TablEdit, Band-in-a-Box, Karaoke MIDI, MuseData, Score Writer, Bagpipe Music Writer e Encore se juntam a MusicXML e MIDI, e as partituras podem ser exportadas como arquivos .flat nativos.
• Coleções virtuais. Todas as partituras, colaborações e curtidas substituem a antiga hierarquia de pastas na biblioteca, acompanhando a biblioteca Flat redesenhada.
• Flat for Education. Atividades de performance com gravações de áudio ou vídeo e opções de backing track, metrônomo e velocidade; entregas em grupo para escrita compartilhada; instruções com rich text; subgrupos de alunos; tarefas do Microsoft Teams agendadas e direcionadas individualmente; descrições ricas e tipos de atividade na biblioteca de recursos.
• Configuração LTI unificada para LTI 1.1 e 1.3, incluindo registro dinâmico. As chamadas anteriores de credenciais do LTI 1.1 foram descontinuadas.
• Estatísticas anuais sobre partituras, contagens de partituras públicas nos perfis e remoção de alguns campos descontinuados há muito tempo.

• Adicionados os métodos getMP3 e getWAV para exportação de áudio
• Adicionado o evento exportProgress, para que uma exportação longa possa exibir o progresso

• As listagens de partituras dos usuários são perfis públicos. Ao listar agora as partituras de um usuário, são retornadas apenas as suas partituras públicas, com nova paginação e ordenação, conforme a mudança anunciada em 2020.
• Os detalhes da partitura passam a expor a URL de edição, os nomes dos instrumentos e qualquer data de exclusão agendada; as coleções informam a contagem de partituras; os perfis públicos mostram as contagens de curtidas e reproduções.
• Flat for Education. Filtre a biblioteca de recursos por tipo de atividade, disciplina e série; os recursos incluem uma descrição de compartilhamento e recursos de privacidade; as atividades podem restringir a reprodução das notas e as faixas de áudio; os envios oferecem suporte aos serviços de notas do LTI 1.1 e 1.3.

• Curtidas paginadas nos perfis de usuário, e o produto que um usuário utiliza nos detalhes da conta.
• As permissões dos recursos informam se quem faz a chamada é o proprietário, um colaborador de usuário ou um colaborador de grupo, com a data em que cada colaborador foi adicionado. Os detalhes da partitura passam a incluir a armadura de clave principal, a data de destaque e a organização.
• Flat for Education. Os convites podem ser reutilizados várias vezes; os envios ganham um estado de avaliado, além de detalhes de reprodução e LTI; uma tarefa só pode ser copiada para a biblioteca de recursos se ainda não estiver lá; as organizações passam a ter suas próprias bibliotecas de recursos com um nível de privacidade para toda a organização.

Leia a estrutura da partitura carregada a partir do seu código.

• Partes e vozes: getNbParts, getPartsUuids, getMeasureVoicesUuids
• Notas: getMeasureNbNotes, getNoteData, playbackPositionToNoteIdx
• O novo parâmetro de URL noAudio desativa a reprodução de áudio
• Corrigido um problema em que setMasterVolume chamava o método interno errado

• Removido o suporte a jQuery no construtor — em vez disso, passe um elemento DOM ou o id dele
• O módulo npm publicado inclui tipos TypeScript
• Builds ES e UMD separados

• Crie links LTI a partir de itens da biblioteca de recursos do Flat for Education para colocá-los diretamente em um curso no LMS.
• A nota máxima de uma atividade passa de 100 para 10.000 pontos.
• Os metadados da partitura (subtítulo, compositor, letrista, arranjador, descrição, licença…) agora também podem ser limpos pela API, e não apenas definidos.

• Resource Library API (beta). Navegue e gerencie bibliotecas de recursos do Flat for Education, com dois novos escopos OAuth2 para acesso completo e somente leitura. As atividades podem ser copiadas para a biblioteca de recursos.
• Alunos de teste. Crie contas de aluno de teste em uma turma para experimentar atividades como um aluno veria.
• As atividades informam o que você pode fazer com elas (editar, publicar, arquivar…), se seus anexos são cópias dedicadas e qualquer problema encontrado. O histórico de envios registra a origem de uma alteração quando ela vem do Google Classroom, Microsoft Teams ou de um LMS.
• Ao redefinir um envio, ele é mantido no lugar em vez de ser excluído; os metadados da turma (nível, habilidades, tamanho) e os detalhes de login da Microsoft nas contas ficam expostos.
• As revisões da partitura retornam suas datas de início e término; os construtores de partitura podem ativar quartos de tom; as cópias podem manter o título original.

• Compassos: getNbMeasures, getMeasuresUuids
• Navegação: goLeft, goRight, scrollToCursor
• Metrônomo: getMetronomeMode, setMetronomeMode
• Velocidade de reprodução: getPlaybackSpeed, setPlaybackSpeed

• Links de login e tokens de acesso delegados. Os administradores do Flat for Education podem criar um link de login para qualquer usuário da organização ou um token de acesso que atue em nome desse usuário: a base para portais personalizados e integrações de login único.
• O japonês em hiragana (ja-HIRA) passa a fazer parte dos locais compatíveis; os comentários públicos passam a expor seu estado de moderação.
• As exportações de áudio retornam o conjunto MP3 como faixa padrão quando ele existe. A opção de solicitar apenas exportações em cache foi removida, já que as exportações de áudio agora são sempre servidas do cache.

• Construtor de partitura. Crie uma partitura em branco sem importar um arquivo MusicXML: informe uma lista de instrumentos e, opcionalmente, a fórmula de compasso, a armadura de clave, a tablatura, os diagramas de acordes e o layout da página.
• Flat for Education. Usuários da organização podem ser criados com uma função; folhas de exercícios podem embaralhar seus exercícios; envios dos alunos listam os exercícios que contêm.

• Faixas de reprodução. Liste as faixas que o Flat gera e sincroniza automaticamente (reprodução como MP3), obtenha os pontos de sincronização do arquivo de reprodução mais recente e receba a URL CDN de uma exportação no corpo da resposta.
• Flat for Education. Os professores podem redefinir a entrega de um aluno; as turmas informam as contas que não puderam ser adicionadas durante uma sincronização; atividades e entregas expõem seu estado e links do Microsoft Teams; cópias de atividades podem ser agendadas; entregas de performance incluem a faixa de áudio salva.
• Os perfis passam a ter imagem de capa, e o id do usuário atual pode ser obtido separadamente.

• loadFlatScore aceita uma sharingKey, permitindo carregar uma partitura compartilhada de forma privada
• Adicionados setTrack, useTrack e seekTrackTo para definir a faixa de áudio dinamicamente

• Exportação de notas. Baixe as notas de uma atividade como arquivo CSV ou Excel.
• As atividades agora incluem seu tipo e uma imagem de capa; ao copiar uma atividade, é possível sobrescrever um rascunho existente com o conteúdo de outra atividade.
• Os colaboradores mostram se ainda estão com um convite pendente.

• Avaliação pela API. Defina notas provisórias e finais, devolva um envio para um aluno e consulte contadores de comentários calculados; a pontuação máxima fica armazenada com a nota.
• Comentários em envios. Crie, liste, atualize e exclua comentários em um envio.
• Opções da atividade. Conjuntos de ferramentas, um limite de reprodução, pontuação máxima, tópicos do Google Classroom, atribuição a alunos específicos, modelos bloqueados e detalhes de atividades de LTI, Canvas e MusicFirst.
• Administradores podem editar o nome de usuário, nome e e-mail de uma conta gerenciada; as listagens de usuários podem ser filtradas por licença ativa.
• Os antigos parâmetros de envio studentComment e returnFeedback foram removidos em favor das novas chamadas de avaliação.

• Arquive e desarquive tarefas e consulte o tipo principal de uma tarefa (nova partitura, modelo ou escrita compartilhada).
• Usuários da organização. Crie contas com nome e sobrenome, classifique e filtre listas de usuários, conte os usuários que correspondem a um filtro e filtre membros de grupos pela origem da sincronização (Google Classroom, Microsoft Teams, Clever).
• Os detalhes da partitura listam os samples de áudio usados na reprodução, com uma lista de instrumentos normalizada que não depende mais dos samples.

Controle a mixagem a partir do seu código e veja o que está sob o cursor.

• Volume e mudo: getMasterVolume, setMasterVolume, getPartVolume, setPartVolume, mutePart, unmutePart
• Solo e reverberação: setPartSoloMode, unsetPartSoloMode, getPartSoloMode, getPartReverb, setPartReverb
• Inspeção: getMeasureDetails, getNoteDetails
• Eventos adicionados: noteDetails, measureDetails, cursorContext

• A especificação passa para OpenAPI 3.0. As versões anteriores eram descritas em OpenAPI 2 (Swagger).
• As partituras passam a expor o arranjador e as estatísticas de reproduções; uma exclusão pode ser agendada para acontecer em breve, em vez de ficar na lixeira.
• Flat for Education. Os anexos das tarefas podem ser arquivos do Google Drive, as turmas incluem os dados do Microsoft Teams e as contas educacionais passam a expor nome e sobrenome.

• As edições de metadados chegam ao editor em tempo real. Ao atualizar, pela API, o título, subtítulo, compositor, letrista ou texto da licença de uma partitura, a alteração é enviada para os editores abertos em tempo real, e uma nova versão é salva. As descrições podem ter o dobro do tamanho (2,000 caracteres).
• As entregas no Education passam a expor seu estado (criada, entregue, devolvida); os metadados de revisão retornam o último evento de modificação.
• O turco passa a fazer parte dos idiomas com suporte; os perfis públicos informam se uma conta pertence à equipe da Flat.

• Adicionado getMIDI
• getMusicXML agora retorna um Uint8Array no nível superior — a resposta não inclui mais a propriedade .data
• O voiceIdx do cursor agora é voiceIdxInStaff

Atualizado para a versão do embed.

• O SDK agora é carregado de flat-embed.com por padrão
• Removidos a ação obsoleta edit e o evento edit
• Removido setNoteColor

• Mais formatos de importação. Arquivos Guitar Pro (GP3, GP4, GP5, GPX, GP), PowerTab, TuxGuitar e MuseScore podem ser importados, e as importações aceitam um nome de arquivo.
• As coleções podem ser listadas em uma coleção pai e informam sua data de criação; as partituras listam as coleções às quais pertencem.
• Os comentários contextuais são vinculados a uma pauta por identificador em vez de por índice, e os direitos do recurso informam se o chamador é um colaborador.

• API de Coleções. Crie, liste, atualize, exclua e restaure coleções, liste suas partituras e adicione ou remova partituras, com três novos escopos OAuth2 para acesso somente leitura, somente adição e acesso total.
• As partituras podem ser restauradas da lixeira; excluir uma partitura sem direitos de administrador faz com que ela seja apenas descompartilhada da sua conta; uma cópia pode ser direcionada para uma coleção específica.
• Os comentários podem ser filtrados por tipo (documento ou inline).
• As exportações de partes agora usam identificadores de parte em vez de índices e, desde setembro de 2019, a listagem de partituras de um usuário retorna apenas partituras públicas.

• Gerenciamento de contas da organização. Administradores podem atualizar contas gerenciadas, excluí-las ou convertê-las em contas de consumidor; as listagens de usuários e convites usam paginação baseada em cursor.
• As turmas passam a ter um estado inativo que pode ser ativado novamente, e informam o domínio do Canvas LMS e a seção do Clever; as tarefas passam a ter um estado de rascunho e um tipo de anexo de exercício.
• Os perfis expõem um tema e os instrumentos tocados.

• Adicionado o método focusScore para dar foco de teclado à incorporação
• Nova propriedade defaultMode na configuração do editor

• As primeiras APIs de educação estão públicas. Gerencie turmas, atividades e envios, contas e convites da organização, credenciais LTI e os grupos e usuários de uma organização: tudo o que uma integração escolar precisa.
• Acesso com escopo definido. Novos escopos do OAuth2 abrangem turmas, atividades e administração da organização, cada um com uma variante somente leitura, para que uma integração solicite apenas o que precisa.

Seu código agora pode inspecionar como a incorporação está configurada e transformá-la em um editor.

• Métodos adicionados: getEmbedConfig, setEditorConfig, edit
• Evento adicionado: edit

O SDK agora consegue carregar partituras a partir de MusicXML e informar o que o leitor está fazendo.

• Métodos adicionados: getAutoZoom, setAutoZoom, loadMusicXML, getMusicXML
• Eventos adicionados: scoreLoaded, cursorPosition, rangeSelection, pause, stop, fullscreen, print
• Testes de integração adicionados

A primeira versão pública da API REST do Flat. Leia e gerencie sua conta, partituras, usuários e grupos a partir dos seus próprios aplicativos e scripts, com OAuth2 para agir em nome de outros usuários do Flat.

Tudo desde então está registrado no changelog da API, e a documentação para desenvolvedores cobre autenticação, a referência e guias.