Registo de alterações para programadores

O painel de programador foi reconstruído com base no que a sua integração pode fazer. Cada capacidade (Embed, OMR, REST API, Import API, LTI) tem um cartão com o seu âmbito, preços e documentação, e as que a sua aplicação já utiliza aparecem primeiro.

• Uma nova secção OMR ao nível da conta, com os seus trabalhos, os seus créditos e o respetivo histórico num só lugar, uma vez que os créditos OMR são partilhados por todas as suas aplicações.
• Experimente o OMR antes de escrever código. O playground aceita um PDF ou fotografias, mostra o número de páginas, o custo por página e o saldo com que ficaria, e depois executa o trabalho quando confirmar. O resultado fica disponível para descarregar em MusicXML; nada é adicionado à sua biblioteca.
• Páginas de aplicação mais claras. Os tokens pessoais, as credenciais OAuth2 e o acesso OMR estão agrupados por aplicação, com destaque para as credenciais que incluem o âmbito OMR.

Abra-o em flat.io/developers.

A nossa especificação REST API passa para OpenAPI 3.1, a API OMR encerra o período beta e os trabalhos do Flat for Education deixam de estar limitados à listagem e criação.

• A API OMR está estável. Os endpoints, campos e comportamento passam agora a seguir o nosso processo habitual de descontinuação antes de qualquer alteração incompatível. Um novo FAQ cobre créditos e faturação, limites e tempos de processamento, qualidade de reconhecimento e idiomas, bem como utilização comercial e privacidade.
• Leia, atualize e elimine trabalhos no Flat for Education. Eliminar um trabalho também remove as respetivas submissões e as cópias dos alunos; arquive-o em vez disso para manter o trabalho.
• Registo de créditos. Uma nova chamada lista o seu histórico de créditos; o saldo continua na chamada de capacidades OMR.
• Os ficheiros Finale (.musx) podem ser importados, numa base 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. Os campos nullable usam a sintaxe 3.1; as ferramentas fixadas em OpenAPI 3.0 precisam de uma atualização. O campo mimeType foi removido dos carregamentos de ficheiros OMR.

• Retenção de dados sob o seu controlo. Os trabalhos OMR passam agora a indicar durante quanto tempo os seus ficheiros são mantidos (30 dias por predefinição), cada trabalho MusicXML inclui a respetiva data de expiração e pode apagar os ficheiros e resultados de um trabalho assim que os tiver recolhido.
• Deteção de funcionalidades antes de iniciar sessão. A chamada de capacidades OMR funciona sem conta e lista os idiomas de reconhecimento suportados com os respetivos nomes.
• Exportação de notação ABC para qualquer revisão da partitura, juntamente com MusicXML, MIDI e os outros formatos. Tal como o MIDI, não inclui toda a gravação tipográfica.
• Trabalhos Free Record podem ser configurados através da API no Flat for Education.
• Os erros provenientes de um fornecedor a montante (por exemplo, o Google Classroom) passam agora a incluir a mensagem localizada do próprio fornecedor.

O motor de OMR do Flat está agora disponível de forma programática através da API para programadores. Envie PDFs ou fotografias, acompanhe o progresso do reconhecimento, reveja os instrumentos detetados e depois importe o resultado como uma partitura editável numa biblioteca do Flat ou exporte em MusicXML ou MIDI. É o mesmo modelo interno que suporta a importação de PDFs e fotografias no editor, agora disponível à escala para as suas próprias aplicações e fluxos de trabalho.

A API dedicada de OMR (v2.24.0) baseia-se na importação de PDFs em segundo plano adicionada à criação de partituras na v2.23.0: peça suporte para tarefas ao importar um ficheiro e faça polling da tarefa até a partitura estar pronta. Consulte o registo de alterações da API para os detalhes de ambos os lançamentos.

A maior atualização da especificação desde 2024, alinhando a API com dois anos de alterações 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 juntam-se a MusicXML e MIDI, e as partituras podem ser exportadas como ficheiros .flat nativos.
• Coleções virtuais. Todas as partituras, colaborações e gostos substituem a hierarquia antiga de pastas na biblioteca, em linha com a biblioteca Flat redesenhada.
• Flat for Education. Trabalhos 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 partilhada; instruções com texto formatado; subgrupos de alunos; tarefas do Microsoft Teams agendadas e direcionadas individualmente; descrições ricas e tipos de tarefa na biblioteca de recursos.
• Configuração LTI unificada para LTI 1.1 e 1.3, incluindo registo dinâmico. As chamadas anteriores de credenciais do LTI 1.1 estão 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 mostrar o progresso

• As listagens de partituras dos utilizadores são perfis públicos. Ao listar agora as partituras de um utilizador, são devolvidas apenas as suas partituras públicas, com nova paginação e ordenação, conforme a alteração anunciada em 2020.
• Os detalhes da partitura passam a expor o URL de edição, os nomes dos instrumentos e qualquer data de eliminação agendada; as coleções indicam o número de partituras; os perfis públicos mostram as contagens de gostos e reproduções.
• Flat for Education. Filtre a biblioteca de recursos por tipo de tarefa, disciplina e ano de escolaridade; os recursos incluem uma descrição de partilha e capacidades de privacidade; as tarefas podem restringir a reprodução das notas e as faixas de áudio; as submissões suportam os serviços de notas LTI 1.1 e 1.3.

• Gostos paginados nos perfis de utilizador e o produto que um utilizador tem nos detalhes da sua conta.
• As permissões dos recursos indicam se quem faz a chamada é o proprietário, um colaborador de utilizador ou um colaborador de grupo, com a data em que cada colaborador foi adicionado. Os detalhes da partitura passam a incluir a armadura principal, a data de destaque e a organização.
• Flat for Education. Os convites podem ser reutilizados várias vezes; as submissões passam a ter um estado de avaliação, 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 as 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 erro em que setMasterVolume chamava o método interno errado

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

• Crie ligações LTI a partir de itens da biblioteca de recursos do Flat for Education, para os colocar diretamente num curso de LMS.
• A nota máxima numa tarefa passa de 100 para 10 000 pontos.
• Os metadados da partitura (subtítulo, compositor, autor da letra, arranjador, descrição, licença…) podem agora ser limpos através da API, e não apenas definidos.

• Resource Library API (beta). Navegue e faça a gestão das bibliotecas de recursos do Flat for Education, com dois novos âmbitos OAuth2 para acesso total e acesso só de leitura. As tarefas podem ser copiadas para a biblioteca de recursos.
• Alunos de teste. Crie contas de aluno de teste numa turma para experimentar tarefas como um aluno as veria.
• As tarefas indicam o que pode fazer com elas (editar, publicar, arquivar…), se os seus anexos são cópias dedicadas e qualquer problema encontrado. O histórico de submissões regista a origem de uma alteração quando esta vem do Google Classroom, Microsoft Teams ou de um LMS.
• Ao repor uma submissão, esta mantém-se no lugar em vez de ser eliminada; os metadados da turma (nível, competências, dimensão) e os detalhes de início de sessão Microsoft nas contas ficam expostos.
• As revisões da partitura devolvem as respetivas datas de início e fim; os criadores de partituras 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

• Ligações de início de sessão e tokens de acesso delegados. Os administradores do Flat for Education podem criar uma ligação de início de sessão para qualquer utilizador da sua organização, ou um token de acesso que atua em nome desse utilizador: a base para portais personalizados e integrações de início de sessão único.
• O japonês em hiragana (ja-HIRA) passa a fazer parte dos idiomas suportados; os comentários públicos passam a expor o respetivo estado de moderação.
• As exportações de áudio devolvem o conjunto MP3 como faixa predefinida quando existe. A opção de pedir apenas exportações em cache foi removida, uma vez que as exportações de áudio são agora sempre servidas a partir da cache.

• Criador de partituras. Crie uma partitura em branco sem importar um ficheiro MusicXML: forneça uma lista de instrumentos e, opcionalmente, a fórmula de compasso, a armadura de clave, a tablatura, os diagramas de acordes e o esquema de página.
• Flat for Education. Os utilizadores da organização podem ser criados com uma função; as fichas de trabalho podem baralhar os seus exercícios; as submissões 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 em MP3), obtenha os pontos de sincronização do ficheiro de reprodução mais recente e receba o URL CDN de uma exportação no corpo da resposta.
• Flat for Education. Os professores podem repor a submissão de um aluno; as turmas indicam as contas que não puderam ser adicionadas durante uma sincronização; as tarefas e submissões expõem o seu estado e ligações do Microsoft Teams; as cópias de tarefas podem ser agendadas; as submissões de desempenho incluem a respetiva faixa de áudio guardada.
• Os perfis passam a ter imagem de capa, e o id do utilizador atual pode ser obtido separadamente.

• loadFlatScore aceita uma sharingKey, permitindo carregar uma partitura partilhada em privado
• Adicionados setTrack, useTrack e seekTrackTo para definir a faixa de áudio dinamicamente

• Exportação de notas. Transfira as notas de uma tarefa como ficheiro CSV ou Excel.
• As tarefas passam a incluir o seu tipo e uma imagem de capa; ao copiar uma tarefa, pode substituir um rascunho existente pelo conteúdo de outra tarefa.
• Os colaboradores mostram se continuam com um convite pendente.

• Avaliação através da API. Defina notas provisórias e finais, devolva uma submissão a um aluno e consulte contadores de comentários calculados; a pontuação máxima é guardada com a nota.
• Comentários nas submissões. Crie, liste, atualize e elimine comentários numa submissão.
• Opções de tarefa. 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 tarefas LTI, Canvas e MusicFirst.
• Os administradores podem editar o nome de utilizador, nome e e-mail de uma conta gerida; as listagens de utilizadores podem ser filtradas por licença ativa.
• Os antigos parâmetros de submissão 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 partilhada).
• Utilizadores da organização. Crie contas com nome próprio e apelido, ordene e filtre listas de utilizadores, conte os utilizadores que correspondem a um filtro e filtre membros de grupos pela respetiva origem de sincronização (Google Classroom, Microsoft Teams, Clever).
• Os detalhes da partitura listam as amostras de áudio usadas na reprodução, com uma lista de instrumentos normalizada que já não depende das amostras.

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

• Volume e silêncio: 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 respetivas estatísticas de reproduções; uma eliminação pode ser agendada para ser executada em breve, em vez de ficar no lixo.
• Flat for Education. Os anexos das tarefas podem ser ficheiros do Google Drive, as turmas incluem os respetivos dados do Microsoft Teams e as contas de educação passam a expor nome próprio e apelido.

• As edições de metadados chegam ao editor em direto. Ao atualizar, através da 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 é guardada uma nova versão. As descrições podem ter o dobro do comprimento (2,000 caracteres).
• As submissões no Education passam a expor o seu estado (criada, entregue, devolvida); os metadados de revisão devolvem o último evento de modificação.
• O turco junta-se aos idiomas suportados; os perfis públicos indicam se uma conta pertence à equipa da Flat.

• Adicionado getMIDI
• getMusicXML passa agora a devolver um Uint8Array ao nível superior — a resposta deixou de incluir a propriedade .data
• O voiceIdx do cursor chama-se agora voiceIdxInStaff

Atualizado para a versão embed.

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

• Mais formatos de importação. É possível importar ficheiros Guitar Pro (GP3, GP4, GP5, GPX, GP), PowerTab, TuxGuitar e MuseScore, e as importações aceitam um nome de ficheiro.
• As coleções podem ser listadas sob uma coleção principal e indicar a respetiva data de criação; as partituras listam as coleções a que pertencem.
• Os comentários contextuais são associados a uma pauta através de um identificador, em vez de um índice, e os direitos do recurso indicam se o autor da chamada é um colaborador.

• API de Coleções. Crie, liste, atualize, elimine e restaure coleções, liste as respetivas partituras e adicione ou remova partituras, com três novos âmbitos OAuth2 para acesso só de leitura, só de adição e acesso total.
• As partituras podem ser restauradas do lixo; eliminar uma partitura sem direitos de administrador deixa, em vez disso, de a partilhar da sua conta; uma cópia pode ter como destino uma coleção específica.
• Os comentários podem ser filtrados por tipo (documento ou em linha).
• As exportações de partes usam agora identificadores de parte em vez de índices e, desde setembro de 2019, a listagem de partituras de um utilizador devolve apenas partituras públicas.

• Gestão de contas de organização. Os administradores podem atualizar contas geridas, eliminá-las ou convertê-las em contas de consumidor; as listagens de utilizadores e convites usam paginação baseada em cursor.
• As turmas passam a ter um estado inativo que pode ser reativado, e passam a indicar o domínio do Canvas LMS e a secção do Clever; os trabalhos 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. Faça a gestão de turmas, tarefas e submissões, contas e convites da organização, credenciais LTI, e dos grupos e utilizadores de uma organização: tudo o que uma integração escolar precisa.
• Acesso com âmbito definido. Os novos âmbitos OAuth2 abrangem turmas, tarefas e administração da organização, cada um com uma variante só de leitura, para que uma integração peça apenas o que precisa.

O seu código pode agora inspecionar como a incorporação está configurada e transformá-la num editor.

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

O SDK passa a conseguir carregar partituras a partir de MusicXML e a indicar o que o leitor está a fazer.

• 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 gira a sua conta, partituras, utilizadores e grupos a partir das suas próprias aplicações e scripts, com OAuth2 para agir em nome de outros utilizadores do Flat.

Tudo o que veio depois está registado no registo de alterações da API, e a documentação para programadores cobre autenticação, a referência e guias.