IMSLP
Leia o IMSLP, a Biblioteca Musical Petrucci: obras, partituras, edições, direitos autorais. Sem chave de API.
Documentação
mcp-imslp
IMSLP, o International Music Score Library Project, também é chamado de Petrucci Music Library. É uma biblioteca gratuita de música clássica mantida por voluntários, que guarda partituras, partes, arranjos e gravações de obras cujos direitos autorais expiraram, junto com o que suas páginas dizem sobre cada compositor. Ela revisa os direitos autorais de cada partitura para o Canadá, os Estados Unidos e a União Europeia separadamente, e publica suas páginas sob CC BY-SA 4.0.
Este servidor conecta um cliente de chat a essa biblioteca. Você pode pesquisar as obras e as pessoas que ela cataloga, ler uma obra com seu número de opus, sua tonalidade, sua instrumentação e o ano em que foi escrita, folhear as edições que uma obra possui com seus editores, revisores e termos de direitos autorais, ler o que a biblioteca diz sobre um compositor e navegar por um gênero, uma tonalidade ou uma instrumentação. Ele lê a biblioteca e cria links para ela, e não precisa de chave de API nem de conta.
Instalação
Instalação em um clique
Claude Code
claude mcp add imslp -- npx -y mcp-imslp
Claude Desktop, Cursor e qualquer cliente que use o formato de configuração padrão
{
"mcpServers": {
"imslp": {
"command": "npx",
"args": ["-y", "mcp-imslp"]
}
}
}
Node 24 ou posterior é necessário, e nenhuma variável de ambiente precisa ser definida.
Com Docker
{
"mcpServers": {
"imslp": {
"command": "docker",
"args": ["run", "-i", "--rm", "ghcr.io/smeet666/mcp-imslp:1.0.1"]
}
}
}
-i mantém o stdin aberto, que é por onde o protocolo trafega, e -t é omitido
porque um TTY reescreve o fluxo. O contêiner precisa de HTTPS de saída para
imslp.org, e nada mais: sem volume, sem porta, sem credencial.
Pacote, sem npm
Baixe mcp-imslp-1.0.1.mcpb de
o lançamento mais recente e
abra-o. Um cliente que suporta pacotes MCP o instala por conta própria, sem npm
e sem arquivo de configuração para editar. O pacote carrega suas dependências,
então nada é baixado no momento da instalação.
O que você pode perguntar
- "O que o IMSLP tem dos noturnos de Chopin?"
- "Leia a página de Erik Satie e me diga quando ele viveu."
- "Liste as edições do Clair de lune de Debussy, com quem publicou cada uma."
- "A edição Henle dessa peça é de uso gratuito nos Estados Unidos?"
- "Mostre-me obras para violoncelo solo na biblioteca."
O caminho comum vai de uma pesquisa a uma obra: search_works nomeia a página de
uma obra, e get_work lê essa página. O mesmo vale para uma pessoa, de
search_people a get_person ou list_person_works.
Ferramentas
| Ferramenta | O que faz |
|---|---|
search_works | Encontra a página de uma obra por título, compositor ou palavras na página. |
search_people | Encontra a categoria sob a qual um compositor, editor, arranjador ou intérprete é arquivado. |
get_work | Lê uma obra: suas facetas, suas seções e seus termos de direitos autorais. |
list_work_files | Folheia as edições que uma obra possui, com seus arquivos. |
list_person_works | Lê as obras que a biblioteca arquiva sob uma pessoa. |
get_person | Lê o que a biblioteca guarda sobre uma pessoa. |
browse_category | Lê as obras arquivadas sob um gênero, uma tonalidade ou uma instrumentação. |
Uma obra é endereçada pelo título de sua página, escrito Work (Composer), como em
Nocturnes, Op.9 (Chopin, Frédéric). Uma pessoa é endereçada por uma categoria,
escrita Category:Surname, Forename. Ambos vêm de uma pesquisa, e o
prefixo Category: pode ser omitido.
A biblioteca intitula uma obra no idioma que seu compositor usou, então Die Zauberflöte
encontra a ópera onde The Magic Flute encontra as páginas escritas sobre ela. Uma
resposta curta para uma obra famosa é um sinal de que o título está em outro idioma.
search_works
Pesquisa as páginas das obras por palavras que aparecem em qualquer lugar delas, então um título, um compositor ou uma dedicatória encontram as obras que as carregam.
| Argumento | Tipo | Obrigatório | O que faz |
|---|---|---|---|
query | string, 1 a 300 caracteres | sim | O que procurar nas páginas das obras. |
limit | inteiro, 1 a 50, padrão 10 | não | Linhas a servir. |
offset | inteiro, 0 ou mais, padrão 0 | não | Linhas a pular, usando o next_offset de uma resposta anterior. |
Em retorno: linhas carregando page, que get_work recebe; work e
composer, lidos desse título; page_url; snippet, as palavras ao redor da
correspondência; size_bytes, words e last_edited como a biblioteca as declara. O
envelope carrega returned, has_more e next_offset, que é o deslocamento para
continuar a leitura. total é sempre null: a biblioteca não publica uma contagem do que uma
pesquisa correspondeu. composer é null em um título escrito fora da
forma Work (Composer), e snippet é null em uma linha que a pesquisa resumiu
com nada.
search_people
Encontra compositores, editores, arranjadores e intérpretes por nome. A biblioteca escreve um nome do seu próprio jeito, sobrenome primeiro, então pesquisar encontra uma pessoa onde adivinhar a grafia não chega a nada.
| Argumento | Tipo | Obrigatório | O que faz |
|---|---|---|---|
query | string, 1 a 300 caracteres | sim | O nome a procurar entre as pessoas da biblioteca. |
limit | inteiro, 1 a 50, padrão 10 | não | Linhas a servir. |
offset | inteiro, 0 ou mais, padrão 0 | não | Linhas a pular, usando o next_offset de uma resposta anterior. |
Em retorno: linhas carregando category, que get_person e
list_person_works recebem; name sem o prefixo; page_url; snippet; e
redirect_to. Uma linha com um redirect_to representa outra categoria e guarda
nenhuma obra própria, então siga a categoria que ela nomeia. O envelope é o que
search_works retorna, e total é null aqui pela mesma razão.
get_work
Lê uma obra: seu título e títulos alternativos, o compositor, o opus e os números de catálogo, o ano de composição e de primeira publicação, a dedicatória, a tonalidade, o idioma, o libretista, a instrumentação, os movimentos, a primeira apresentação, o estilo e o período.
| Argumento | Tipo | Obrigatório | O que faz |
|---|---|---|---|
page | string, 1 a 300 caracteres | um de dois | O título da página, escrito Work (Composer). |
pageid | inteiro, positivo | um de dois | O id da página que uma pesquisa retornou, como alternativa a page. |
Em retorno: cada faceta acima, cada null quando a página a deixa vazia, e
cada uma na redação que a página usou, então ca.1830 permanece ca.1830. Ao lado delas vêm
genre_categories, que browse_category recebe; external_links e
authorities, os registros da obra na VIAF, LCCN, WorldCat, BNF e GND;
sections, com o número de entradas que o site conta em cada; e
copyright_summary, uma entrada por declaração distinta, com o número de
edições que a carregam. editions guarda cada edição com seus arquivos, e vira
null com editions_truncated verdadeiro quando a obra tem mais de cinco, o que
list_work_files então folheia. redirected_from nomeia o título pedido
quando ele levou até aqui, e pageid é null para uma obra endereçada por título.
list_work_files
Lê as partituras e as gravações de uma obra, edição por edição. Uma edição é um conjunto de arquivos publicados sob um conjunto de termos: o editor, o revisor e a declaração de direitos autorais pertencem à edição, e os arquivos ficam sob ela. Um bloco de gravações carrega intérpretes e nenhuma declaração de direitos autorais.
| Argumento | Tipo | Obrigatório | O que faz |
|---|---|---|---|
page | string, 1 a 300 caracteres | um de dois | O título da página, escrito Work (Composer). |
pageid | inteiro, positivo | um de dois | O id da página que uma pesquisa retornou, como alternativa a page. |
section | string, 1 a 80 caracteres | não | Uma seção da página, na própria redação: Scores, Parts, Recordings, Arrangements and Transcriptions. Correspondida sem considerar maiúsculas e minúsculas. |
limit | inteiro, 1 a 100, padrão 10 | não | Edições a servir. |
offset | inteiro, 0 ou mais, padrão 0 | não | Edições a pular. |
Em retorno: editions, cada uma com seu section, publisher_info, editor,
copyright e files. Um arquivo carrega imslp_id, description, format e
format_code, pages, size_bytes, downloads, rating, uploader,
uploaded_on, as siglas e o nome da biblioteca que o digitalizou, e blocked,
que é verdadeiro enquanto o IMSLP revisa os direitos autorais desse arquivo. downloads é
null em uma entrada que não imprime contador, e rating é null quando ninguém
votou. Ao lado vêm editions_on_page, editions_in_section, returned,
has_more e sections. Um section que não corresponde a nada volta com as
seções que a página realmente guarda, então uma restrição nunca é lida como uma obra sem
partituras.
list_person_works
Lê as obras que a biblioteca arquiva sob uma pessoa: o que um compositor escreveu, e também o que um editor, um arranjador ou um intérprete tem em seu crédito.
| Argumento | Tipo | Obrigatório | O que faz |
|---|---|---|---|
category | string, 1 a 300 caracteres | sim | A categoria da pessoa, escrita Category:Surname, Forename. |
limit | inteiro, 1 a 100, padrão 25 | não | Linhas a servir. |
cursor | string, 1 a 500 caracteres | não | O cursor que uma resposta anterior nomeou, passado de volta como foi dado. |
Em retorno: linhas carregando page, work, composer, pageid e page_url,
com has_more e cursor para continuar. total é sempre null: a biblioteca
não publica uma contagem do que uma categoria contém. Uma categoria que a biblioteca não possui
responde da mesma forma que uma vazia, então uma resposta sem linhas é um motivo para verificar
a grafia com search_people.
get_person
Lê o que a biblioteca guarda sobre uma pessoa: o nome como sua página o imprime, as datas de vida que ela declara, os outros nomes sob os quais ela os arquiva, os registros que guardam um registro deles, e os endereços que ela aponta fora do site.
| Argumento | Tipo | Obrigatório | O que faz |
|---|---|---|---|
category | string, 1 a 300 caracteres | sim | A categoria da pessoa, escrita Category:Surname, Forename. |
Em retorno: category, catalogued_as com o sobrenome primeiro, name como a
página o imprime, life_dates na redação que a página usou, alternative_names
e aliases como linhas publicadas, authorities com o registro e o
identificador na VIAF, LCCN, WorldCat, BNF e GND, external_links, e
page_url. life_dates é null em uma página que não declara nenhum. Isto lê a pessoa;
list_person_works lê as obras.
browse_category
Lê as obras arquivadas sob uma categoria: um gênero, uma tonalidade, uma instrumentação ou um
período. get_work devolve esses nomes para uma obra sob genre_categories,
e passar um deles alcança uma categoria que a biblioteca possui.
| Argumento | Tipo | Obrigatório | O que faz |
|---|---|---|---|
category | string, 1 a 300 caracteres | sim | A categoria a ler, na redação da biblioteca: For piano, Nocturnes, B-flat minor. |
limit | inteiro, 1 a 100, padrão 25 | não | Linhas a servir. |
cursor | string, 1 a 500 caracteres | não | O cursor que uma resposta anterior nomeou, passado de volta como foi dado. |
Em retorno: as linhas que list_person_works devolve, com o mesmo has_more e
cursor, e total em null. A biblioteca lê uma categoria por vez, então uma
pergunta que nomeia tanto um gênero quanto um instrumento é respondida navegando por um
deles e lendo o outro de cada obra com get_work.
Status de direitos autorais
Uma partitura no IMSLP carrega um status por jurisdição, e a biblioteca revisa
Canadá, Estados Unidos e União Europeia. Um arquivo que lê
Public Domain - Non-PD US é livre no Canadá e na União Europeia e
protegido nos Estados Unidos. Este servidor relata o status como publicado, por
jurisdição, sob copyright_summary em uma obra e sob copyright em uma
edição, com restrictions nomeando os lugares que uma declaração exclui. Um
restrictions vazio não diz nada sobre os países que o IMSLP deixa de fora de sua revisão.
Configuração
Toda variável é opcional. Defina-as no bloco env da configuração do seu cliente.
| Variável | Padrão | O que faz |
|---|---|---|
IMSLP_USER_AGENT | a identidade do projeto | Nomeia seu aplicativo. A identidade do projeto é anexada para que o IMSLP possa alcançar uma pessoa. |
IMSLP_MIN_INTERVAL_MS | 2500 | Intervalo entre duas solicitações, de 2000 a 60000. Um valor abaixo do mínimo é recusado e este é usado. |
IMSLP_TIMEOUT_MS | 30000 | Prazo para uma solicitação, de 1000 a 120000. |
IMSLP_MAX_RETRIES | 3 | Tentativas após uma falha transitória, de 0 a 10. |
IMSLP_CACHE_TTL_MS | 900000 | Quanto tempo uma página permanece na memória, de 0 a 86400000. |
IMSLP_CACHE_MAX_ENTRIES | 100 | Páginas mantidas na memória de uma vez, de 0 a 10000. |
IMSLP_LOG_LEVEL | error | silent, error, info ou debug, escrito em stderr. |
Um valor fora do intervalo cai para o padrão, e o motivo é escrito em stderr.
Erros
Toda falha carrega um de seis códigos, uma mensagem e, onde ajuda, uma dica nomeando o próximo passo.
| Código | O que aconteceu | O que fazer |
|---|---|---|
not_found | O IMSLP respondeu, e a página solicitada está ausente. | Verifique o título com search_works. |
invalid_input | Os argumentos foram recusados antes de qualquer solicitação sair. | Leia a mensagem, que nomeia o argumento. |
rate_limited | O IMSLP pediu que este cliente diminuísse o ritmo. | Aguarde o número de segundos que a dica nomeia e chame novamente com os mesmos argumentos. O trabalho ainda está na biblioteca. |
parse_failure | A página carregou e o conteúdo esperado estava ausente. | Reporte em o rastreador de problemas. |
network_error | A solicitação não foi concluída. | Tente novamente em breve. |
timeout | A solicitação passou do prazo. | Aumente IMSLP_TIMEOUT_MS, ou peça menos linhas. |
Como biblioteca
A camada que lê o IMSLP é publicada por conta própria, com seu ritmo, seu cache e seus erros, e sem protocolo anexado.
import { ImslpClient } from "mcp-imslp/client";
const client = new ImslpClient();
const { data, cached } = await client.getWork({ page: "Nocturnes, Op.9 (Chopin, Frédéric)" });
console.log(data.title, data.copyright_summary, cached);
renderPage, getWork, search, categoryMembers e getPerson cada um responde
{ data, cached }, e lançam um ImslpError carregando um dos seis códigos. O
piso de dois segundos entre solicitações também vale aqui.
Ritmo e atribuição
O IMSLP publica Crawl-delay: 2 em seu robots.txt, então as solicitações saem uma de cada
vez com pelo menos dois segundos entre elas, e esse piso vale independentemente de como o
servidor está configurado. O User-Agent sempre termina com a identidade do projeto e
um endereço onde uma pessoa pode ser alcançada.
As leituras passam pela API MediaWiki em /api.php e pelo endpoint de listagem
que o IMSLP documenta em sua própria página IMSLP:API. O robots.txt desautoriza
/index.php, /images/, /imglnks/, /wiki/File:, /works e /library/,
e este servidor não constrói nenhum endereço sob nenhum deles: ele devolve o link para
a página da obra, que é o que uma resposta credita.
A biblioteca publica suas páginas sob CC BY-SA 4.0, então qualquer coisa exibida deste servidor credita o IMSLP e vincula a página de onde veio.
Privacidade
Este servidor não coleta nada sobre você e não envia nada ao seu autor. Ele roda
na sua máquina, contata imslp.org e nada mais, mantém suas respostas na memória
enquanto roda, e não grava nada em disco.
PRIVACY.md declara o que uma solicitação carrega e quais configurações mudam
qualquer parte disso.
Desenvolvimento
npm install
npm run build:fixtures
npm test
npm run check
Os testes rodam contra fixtures geradas e não fazem nenhuma solicitação de rede. A suíte ao vivo,
npm run test:live, faz uma solicitação por rota e roda todas as noites contra o
próprio site.
Contribuindo
Problemas e pull requests são bem-vindos em o repositório. Veja CONTRIBUTING.md.
Licença
MIT, veja LICENSE. O catálogo e as páginas pertencem ao IMSLP e seus contribuidores, publicados sob CC BY-SA 4.0.
mcp-imslp (francês)
IMSLP, o International Music Score Library Project, também é chamado de Petrucci Music Library. É uma biblioteca livre de música clássica mantida por voluntários, que reúne partituras, partes separadas, arranjos e gravações de obras em domínio público, com o que suas páginas dizem sobre cada compositor. Ela verifica os direitos de cada partitura para Canadá, Estados Unidos e União Europeia separadamente, e publica suas páginas sob CC BY-SA 4.0.
Este servidor conecta um cliente de conversa a essa biblioteca. Pode-se buscar as obras e pessoas que ela cataloga, ler uma obra com seu número de opus, tonalidade, instrumentação e ano de composição, navegar pelas edições de uma obra com seus editores e condições de direitos, ler o que a biblioteca diz sobre um compositor, e explorar um gênero, tonalidade ou instrumentação. Ele lê a biblioteca e retorna para ela, sem chave de API nem conta.
Instalação
Instalação em um clique
Claude Code
claude mcp add imslp -- npx -y mcp-imslp
Claude Desktop, Cursor, e qualquer cliente no formato de configuração padrão
{
"mcpServers": {
"imslp": {
"command": "npx",
"args": ["-y", "mcp-imslp"]
}
}
}
Node 24 ou mais recente é necessário, e nenhuma variável de ambiente precisa ser preenchida.
Com Docker
{
"mcpServers": {
"imslp": {
"command": "docker",
"args": ["run", "-i", "--rm", "ghcr.io/smeet666/mcp-imslp:1.0.1"]
}
}
}
-i mantém a entrada padrão aberta, que é o canal do protocolo, e -t é
omitido porque um TTY reescreve o fluxo. O contêiner precisa de acesso HTTPS
de saída para imslp.org, e nada mais: nenhum volume, nenhuma porta, nenhum
identificador.
Bundle, sem npm
Baixe mcp-imslp-1.0.1.mcpb de
a última publicação
e abra-o. Um cliente que gerencia bundles MCP o instala sozinho, sem npm e
sem arquivo de configuração para modificar. O bundle carrega suas dependências, então
nada é baixado na instalação.
O que se pode pedir
- « O IMSLP tem os noturnos de Chopin? »
- « Leia a página de Erik Satie e me diga quando ele viveu. »
- « Liste as edições do Clair de lune de Debussy, com quem publicou cada uma. »
- « A edição Henle desta peça é de domínio público nos Estados Unidos? »
- « Mostre-me obras para violoncelo solo na biblioteca. »
O caminho comum vai de uma busca a uma obra: search_works nomeia a página
de uma obra, e get_work lê essa página. O mesmo vale para uma pessoa, de
search_people para get_person ou list_person_works.
As ferramentas
| Ferramenta | O que faz |
|---|---|
search_works | Encontra a página de uma obra pelo título, compositor ou palavras. |
search_people | Encontra a categoria sob a qual uma pessoa é classificada. |
get_work | Lê uma obra: suas características, seções e direitos. |
list_work_files | Percorre as edições de uma obra, com seus arquivos. |
list_person_works | Lê as obras que a biblioteca classifica sob uma pessoa. |
get_person | Lê o que a biblioteca contém sobre uma pessoa. |
browse_category | Lê as obras classificadas sob um gênero, tonalidade, formação. |
Uma obra é endereçada pelo título de sua página, escrito Œuvre (Compositeur), como
Nocturnes, Op.9 (Chopin, Frédéric). Uma pessoa é endereçada por uma categoria,
escrita Category:Nom, Prénom. Ambos vêm de uma busca, e o prefixo
Category: pode ser omitido.
A biblioteca intitula uma obra no idioma de seu compositor, portanto
Die Zauberflöte encontra a ópera onde La Flûte enchantée encontra as páginas
escritas sobre ela. Uma resposta escassa sobre uma obra famosa é sinal de um
título em outro idioma.
search_works
Busca nas páginas das obras as palavras que nelas constam, onde quer que estejam: um título, um compositor ou uma dedicatória encontram as obras que os carregam.
| Argumento | Tipo | Obrigatório | O que faz |
|---|---|---|---|
query | string, 1 a 300 caracteres | sim | O que se busca nas páginas das obras. |
limit | inteiro, 1 a 50, padrão 10 | não | Linhas a servir. |
offset | inteiro, 0 ou mais, padrão 0 | não | Linhas a pular, com o next_offset de uma resposta anterior. |
Em retorno: linhas com page, que get_work retoma; work e
composer, lidos nesse título; page_url; snippet, as palavras ao redor da
correspondência; size_bytes, words e last_edited tais como a biblioteca
as publica. O envelope traz returned, has_more e next_offset, o offset
de onde retomar. total vale sempre null: a biblioteca não publica nenhuma
contagem do que uma busca encontrou. composer vale null em um título escrito
fora da forma Œuvre (Compositeur), e snippet vale null em uma linha
que a busca não resumiu por nada.
search_people
Encontra compositores, editores, arranjadores e intérpretes pelo nome. A biblioteca escreve um nome à sua maneira, sobrenome primeiro, portanto a busca encontra uma pessoa onde uma ortografia adivinhada não alcança nada.
| Argumento | Tipo | Obrigatório | O que faz |
|---|---|---|---|
query | string, 1 a 300 caracteres | sim | O nome procurado entre as pessoas da biblioteca. |
limit | inteiro, 1 a 50, padrão 10 | não | Linhas a servir. |
offset | inteiro, 0 ou mais, padrão 0 | não | Linhas a pular, com o next_offset de uma resposta anterior. |
Em retorno: linhas com category, que get_person e
list_person_works retomam; name sem o prefixo; page_url; snippet;
e redirect_to. Uma linha com um redirect_to substitui outra
categoria e não contém nenhuma obra, portanto siga a categoria que ela nomeia.
O envelope é o de search_works, e total vale null pela mesma
razão.
get_work
Lê uma obra: seu título e títulos alternativos, o compositor, os números de opus e de catálogo, o ano de composição e o de primeira publicação, a dedicatória, a tonalidade, o idioma, o libretista, a instrumentação, os movimentos, a estreia, o estilo e o período.
| Argumento | Tipo | Obrigatório | O que faz |
|---|---|---|---|
page | string, 1 a 300 caracteres | um dos dois | O título da página, escrito Œuvre (Compositeur). |
pageid | inteiro, positivo | um dos dois | O identificador de página retornado por uma busca. |
Em retorno: cada uma das características acima, null quando a página a
deixa vazia, e nos termos da página, portanto ca.1830 permanece ca.1830.
Ao lado vêm genre_categories, que browse_category retoma;
external_links e authorities, os registros da obra no VIAF, na LCCN, no
WorldCat, na BNF e na GND; sections, com o número de entradas que o site
conta em cada um; e copyright_summary, uma entrada por menção distinta,
com o número de edições que a carregam. editions contém cada edição e
seus arquivos, e passa para null com editions_truncated verdadeiro além de cinco
edições, que list_work_files percorre então. redirected_from nomeia o título
solicitado quando ele levou até aqui, e pageid vale null para uma obra endereçada pelo
título.
list_work_files
Lê as partituras e gravações de uma obra, edição por edição. Uma edição é um conjunto de arquivos publicados sob as mesmas condições: o editor, o revisor e a menção de direitos pertencem à edição, e os arquivos se organizam abaixo dela. Um bloco de gravações traz intérpretes e nenhuma menção de direitos.
| Argumento | Tipo | Obrigatório | O que faz |
|---|---|---|---|
page | string, 1 a 300 caracteres | um dos dois | O título da página, escrito Œuvre (Compositeur). |
pageid | inteiro, positivo | um dos dois | O identificador de página retornado por uma busca. |
section | string, 1 a 80 caracteres | não | Uma seção da página, em seus próprios termos: Scores, Parts, Recordings, Arrangements and Transcriptions. A caixa é ignorada. |
limit | inteiro, 1 a 100, padrão 10 | não | Edições a servir. |
offset | inteiro, 0 ou mais, padrão 0 | não | Edições a pular. |
Em retorno: editions, cada uma com sua section, seu publisher_info, seu
editor, seu copyright e seus files. Um arquivo traz imslp_id,
description, format e format_code, pages, size_bytes, downloads,
rating, uploader, uploaded_on, o sigla e o nome da biblioteca que o
digitalizou, e blocked, verdadeiro enquanto o IMSLP verifica os direitos desse arquivo.
downloads vale null em uma entrada sem contador, e rating vale null
quando ninguém votou. Vêm também editions_on_page,
editions_in_section, returned, has_more e sections. Uma section que não
corresponde a nada retorna com as seções que a página contém, portanto uma
restrição nunca se lê como uma obra sem partitura.
list_person_works
Lê as obras que a biblioteca classifica sob uma pessoa: o que um compositor escreveu, e também o que um revisor, arranjador ou intérprete tem crédito.
| Argumento | Tipo | Obrigatório | O que faz |
|---|---|---|---|
category | string, 1 a 300 caracteres | sim | A categoria da pessoa, escrita Category:Nom, Prénom. |
limit | inteiro, 1 a 100, padrão 25 | não | Linhas a servir. |
cursor | string, 1 a 500 caracteres | não | O cursor nomeado por uma resposta anterior, dado novamente como está. |
Em retorno: linhas com page, work, composer, pageid e
page_url, com has_more e cursor para continuar. total vale sempre
null: a biblioteca não publica nenhuma contagem do que uma categoria contém.
Uma categoria que ela não contém responde como uma categoria vazia, portanto uma
resposta sem linha convida a verificar a ortografia com search_people.
get_person
Lê o que a biblioteca contém sobre uma pessoa: o nome como sua página o imprime, as datas de vida que ela indica, os outros nomes sob os quais ela a classifica, os registros que mantêm uma notícia sobre ela, e os endereços para os quais ela encaminha fora do site.
| Argumento | Tipo | Obrigatório | O que faz |
|---|---|---|---|
category | string, 1 a 300 caracteres | sim | A categoria da pessoa, escrita Category:Nom, Prénom. |
Em retorno: category, catalogued_as com o sobrenome primeiro, name tal
como a página o imprime, life_dates nos termos da página,
alternative_names e aliases como linhas publicadas, authorities com o
registro e o identificador no VIAF, na LCCN, no WorldCat, na BNF e na GND,
external_links, e page_url. life_dates vale null em uma página que não
indica nenhuma. Esta ferramenta lê a pessoa; list_person_works lê as obras.
browse_category
Lê as obras classificadas sob uma categoria: um gênero, uma tonalidade, uma
instrumentação ou um período. get_work retorna esses nomes para uma obra sob
genre_categories, e fornecer um novamente alcança uma categoria que a biblioteca
contém.
| Argumento | Tipo | Obrigatório | O que faz |
|---|---|---|---|
category | string, 1 a 300 caracteres | sim | A categoria a ler, nos termos da biblioteca: For piano, Nocturnes, B-flat minor. |
limit | inteiro, 1 a 100, padrão 25 | não | Linhas a servir. |
cursor | string, 1 a 500 caracteres | não | O cursor nomeado por uma resposta anterior, fornecido novamente tal como está. |
Em retorno: as linhas que list_person_works retorna, com os mesmos
has_more e cursor, e total a null. A biblioteca lê uma categoria por
vez, portanto uma pergunta que nomeia um gênero e um instrumento se responde
percorrendo um e lendo o outro em cada obra com get_work.
O status de direitos autorais
Uma partitura carrega no IMSLP um status por jurisdição, e a biblioteca
verifica o Canadá, os Estados Unidos e a União Europeia. Um arquivo marcado
Public Domain - Non-PD US é livre no Canadá e na União Europeia, e
protegido nos Estados Unidos. Este servidor retorna o status tal como é publicado,
jurisdição por jurisdição, sob copyright_summary para uma obra e sob
copyright para uma edição, com restrictions que nomeia os lugares que uma
menção exclui. Um restrictions vazio não afirma nada sobre os países que o IMSLP
deixa fora de sua verificação.
Configuração
Cada variável é opcional. Elas são definidas no bloco env da
configuração do cliente.
| Variável | Padrão | O que faz |
|---|---|---|
IMSLP_USER_AGENT | a identidade do projeto | Nomeia seu aplicativo. A identidade do projeto é adicionada para que o IMSLP possa contatar uma pessoa. |
IMSLP_MIN_INTERVAL_MS | 2500 | Intervalo entre duas requisições, de 2000 a 60000. Um valor abaixo do mínimo é recusado em favor deste. |
IMSLP_TIMEOUT_MS | 30000 | Tempo limite de uma requisição, de 1000 a 120000. |
IMSLP_MAX_RETRIES | 3 | Tentativas após uma falha temporária, de 0 a 10. |
IMSLP_CACHE_TTL_MS | 900000 | Duração durante a qual uma página permanece em memória, de 0 a 86400000. |
IMSLP_CACHE_MAX_ENTRIES | 100 | Páginas mantidas em memória por vez, de 0 a 10000. |
IMSLP_LOG_LEVEL | error | silent, error, info ou debug, escrito na saída de erro. |
Um valor fora de seu intervalo recai no padrão, e o motivo é escrito na saída de erro.
Erros
Cada falha carrega um dos seis códigos, uma mensagem e, quando ajuda, uma indicação do próximo passo.
| Código | O que aconteceu | O que fazer |
|---|---|---|
not_found | O IMSLP respondeu, e a página solicitada está ausente. | Verifique o título com search_works. |
invalid_input | Os argumentos foram recusados antes de qualquer requisição. | Leia a mensagem, que nomeia o argumento. |
rate_limited | O IMSLP pede que este cliente desacelere. | Aguarde os segundos indicados e chame novamente com os mesmos argumentos. A obra ainda está na biblioteca. |
parse_failure | A página carregou e o conteúdo esperado está ausente. | Reporte em o rastreador de incidentes. |
network_error | A requisição não foi concluída. | Tente novamente em breve. |
timeout | A requisição excedeu seu tempo limite. | Aumente IMSLP_TIMEOUT_MS, ou peça menos linhas. |
Como biblioteca
A camada que lê o IMSLP é publicada sozinha, com seu ritmo, seu cache e seus erros, sem protocolo anexado.
import { ImslpClient } from "mcp-imslp/client";
const client = new ImslpClient();
const { data, cached } = await client.getWork({ page: "Nocturnes, Op.9 (Chopin, Frédéric)" });
console.log(data.title, data.copyright_summary, cached);
renderPage, getWork, search, categoryMembers e getPerson respondem
cada um { data, cached }, e levantam uma ImslpError carregando um dos seis códigos.
O mínimo de dois segundos entre duas requisições também se aplica aqui.
Ritmo e atribuição
O IMSLP publica Crawl-delay: 2 em seu robots.txt, portanto as requisições partem uma
a uma com pelo menos dois segundos entre elas, e esse mínimo se mantém independentemente
da configuração. O User-Agent sempre termina com a identidade do
projeto e um endereço para contatar uma pessoa.
As leituras passam pela API MediaWiki /api.php e pelo ponto de entrada
que o IMSLP documenta em sua página IMSLP:API. O robots.txt proíbe /index.php,
/images/, /imglnks/, /wiki/File:, /works e /library/, e este servidor não
constrói nenhum endereço sob esses caminhos: ele retorna o link da página da
obra, que é o que uma resposta credita.
A biblioteca publica suas páginas sob CC BY-SA 4.0, portanto tudo o que este servidor retorna atribui ao IMSLP e aponta para a página original.
Privacidade
Este servidor não coleta nada sobre você e não envia nada ao seu autor. Ele roda em
sua máquina, contata apenas imslp.org, mantém suas respostas em memória enquanto
roda, e não escreve nada no disco. PRIVACY.md diz o que uma
requisição carrega e quais ajustes mudam isso.
Desenvolvimento
npm install
npm run build:fixtures
npm test
npm run check
Os testes são executados em fixtures geradas e não emitem nenhuma requisição.
A suíte ao vivo, npm run test:live, emite uma requisição por rota e roda
toda noite contra o próprio site.
Contribuindo
Tickets e propostas de modificação são bem-vindos em o repositório. Veja CONTRIBUTING.md.
Licença
MIT, veja LICENSE. O catálogo e as páginas pertencem ao IMSLP e a seus contribuidores, publicados sob CC BY-SA 4.0.