cifraclub-wrapper

Wrapper em TypeScript para buscar, listar, baixar e transpor cifras do Cifra Club.

A biblioteca permite:

- pesquisar músicas
- listar músicas de um songbook
- baixar cifras completas
- transpor tons
- ajustar capo
- filtrar apenas letras, acordes ou remover tablaturas

Ela expõe uma API simples para trabalhar com metadados e conteúdo processado das cifras.

## Instalação

npm install cifraclub-wrapper

ou

yarn add cifraclub-wrapper

Importação

import CifraClub from 'cifraclub-wrapper'

Também é possível importar os tipos e classes auxiliares:

import CifraClub, { Cifra, CifraList, CifraMeta } from 'cifraclub-wrapper'

Visão geral

A biblioteca possui três estruturas principais:

CifraClub

Classe principal da API.

Responsável por:

• pesquisar músicas
• listar músicas de um songbook
• baixar várias cifras
• carregar uma cifra individual

Cifra

Representa uma cifra individual já carregada.

Permite:

• acessar metadados
• acessar conteúdo estruturado
• transpor a cifra
• alterar capo
• extrair apenas letras
• extrair apenas acordes
• remover tablaturas

CifraList

Representa uma coleção de cifras.

Permite aplicar filtros em lote, como:

• lyrics()
• chords()
• noTabs()

Exemplo rápido

import CifraClub from 'cifraclub-wrapper'

async function main() {
  const results = await CifraClub.search('quanta coisa tenho feito')

  if (!results.length) return

  const cifra = await CifraClub.get(results[0])

  if (!cifra) return

  console.log(cifra.metadata)
  console.log(cifra.data)
}

main()

API

CifraClub.search(search: string): Promise<CifraMeta[]>

Pesquisa músicas no Cifra Club a partir de um texto.

Exemplo

const results = await CifraClub.search('Aclame ao Senhor')

console.log(results)

Retorno

Um array de objetos CifraMeta com dados básicos da música encontrada.

Observação

O retorno da busca é inicial e pode não conter todos os campos completos até que a cifra seja carregada com get().

CifraClub.list(id: string): Promise<CifraMeta[]>

Lista as músicas de um songbook pelo ID.

Exemplo

const musics = await CifraClub.list('123456')

console.log(musics)

Retorno

Um array de CifraMeta com informações mais completas, incluindo:

• tom original
• capo
• afinação
• versão
• id da música
• autor

CifraClub.get(data: CifraMeta): Promise<Cifra | boolean>

Carrega uma cifra a partir de um objeto CifraMeta.

Exemplo

const results = await CifraClub.search('Porque Ele Vive')
const cifra = await CifraClub.get(results[0])

if (cifra) {
  console.log(cifra.metadata)
  console.log(cifra.data)
}

Retorno

Retorna uma instância de Cifra em caso de sucesso, ou false em caso de erro.

CifraClub.downloadList(data?: CifraMeta[]): Promise<CifraList>

Baixa várias cifras e devolve uma coleção CifraList.

Exemplo

const musics = await CifraClub.list('123456')
const cifras = await CifraClub.downloadList(musics)

console.log(cifras.data)

Classe Cifra

Representa uma cifra já carregada e processada.

Propriedades

html_url: string

URL pública da cifra no site.

metadata

Retorna os metadados da cifra.

console.log(cifra.metadata)

data

Retorna o conteúdo estruturado da cifra.

console.log(cifra.data)

Formato do conteúdo:

Array<{
  type: string
  text: string
}>

Exemplo:

[
  { type: 'indicator_chords', text: '[Intro] C  G  Am  F' },
  { type: 'lyrics', text: 'Quanta coisa tenho feito...' },
  { type: 'chords', text: 'C      G      Am      F' }
]

Métodos

await cifra.get()

Carrega ou recarrega a cifra.

Exemplo

await cifra.get()

cifra.lyrics(): Cifra

Retorna uma nova instância contendo apenas linhas de letra.

Exemplo

const lyricsOnly = cifra.lyrics()

console.log(lyricsOnly.data)

cifra.chords(): Cifra

Retorna uma nova instância contendo apenas linhas de acordes e indicadores.

Exemplo

const chordsOnly = cifra.chords()

console.log(chordsOnly.data)

cifra.noTabs(): Cifra

Retorna uma nova instância sem linhas de tablatura.

Exemplo

const semTabs = cifra.noTabs()

console.log(semTabs.data)

await cifra.transpose(halfsteps = 0)

Transpõe a cifra em semitons.

Exemplo

await cifra.transpose(2)   // sobe 2 semitons
await cifra.transpose(-1)  // desce 1 semitom

Observação

A transposição altera o conteúdo carregado da cifra.

await cifra.capo(capo = 0)

Altera o capo da música e recalcula o tom exibido nos metadados.

Exemplo

await cifra.capo(2)

console.log(cifra.metadata.tone)

Classe CifraList

Coleção de cifras.

Propriedade

data: Cifra[]

Array com todas as cifras carregadas.

Métodos

push(...items)

Adiciona cifras à lista.

list.push(cifra1, cifra2)

lyrics(): CifraList

Aplica lyrics() em todas as cifras da lista.

const onlyLyrics = list.lyrics()

chords(): CifraList

Aplica chords() em todas as cifras da lista.

const onlyChords = list.chords()

noTabs(): CifraList

Remove tablaturas de todas as cifras da lista.

const noTabs = list.noTabs()

Tipo CifraMeta

Estrutura de metadados usada pela biblioteca.

type CifraMeta = {
  path: string
  position: number
  hash: URLSearchParams
  name: string
  author: string
  tone_songbook: string
  capo_songbook: number
  tone: string
  id: string
  tuning: string
  version: string
  minor: boolean
}

Campos principais

name

Nome da música.

author

Nome do artista ou autor.

tone_songbook

Tom original informado no songbook.

capo_songbook

Capotraste original informado.

tone

Tom calculado considerando capo.

tuning

Afinação da música.

version

Versão da cifra.

minor

Indica se a música está em tonalidade menor.

Tipos de linha no conteúdo

O conteúdo processado da cifra é dividido em linhas com tipos.

Os tipos mais comuns são:

lyrics

Linha de letra.

chords

Linha de acordes.

tab

Linha de tablatura.

indicator_lyrics

Linha de seção com letra, como [Refrão].

indicator_chords

Linha de seção com acordes, como [Intro].

empty

Linha vazia.

Exemplos completos

Buscar e carregar a primeira música encontrada

import CifraClub from 'cifraclub-wrapper'

async function main() {
  const results = await CifraClub.search('Aclame ao Senhor')

  if (!results.length) {
    console.log('Nenhuma música encontrada')
    return
  }

  const cifra = await CifraClub.get(results[0])

  if (!cifra) {
    console.log('Erro ao carregar cifra')
    return
  }

  console.log('Metadados:', cifra.metadata)
  console.log('Conteúdo:', cifra.data)
}

main()

Baixar várias cifras de um songbook

import CifraClub from 'cifraclub-wrapper'

async function main() {
  const musics = await CifraClub.list('123456')
  const list = await CifraClub.downloadList(musics)

  console.log(list.data.length)
}

main()

Trabalhar apenas com letras

const cifra = await CifraClub.get(meta)

if (cifra) {
  const onlyLyrics = cifra.lyrics()
  console.log(onlyLyrics.data)
}

Trabalhar apenas com acordes

const cifra = await CifraClub.get(meta)

if (cifra) {
  const onlyChords = cifra.chords()
  console.log(onlyChords.data)
}

Remover tablaturas

const cifra = await CifraClub.get(meta)

if (cifra) {
  const clean = cifra.noTabs()
  console.log(clean.data)
}

Transpor música

const cifra = await CifraClub.get(meta)

if (cifra) {
  await cifra.transpose(1)
  console.log(cifra.data)
}

Ajustar capo

const cifra = await CifraClub.get(meta)

if (cifra) {
  await cifra.capo(3)
  console.log(cifra.metadata.tone)
}

Observações

Esta biblioteca depende da estrutura atual das respostas e páginas do Cifra Club. Mudanças no HTML ou nos endpoints utilizados podem impactar o funcionamento.

As operações de download em lote incluem pequeno intervalo entre requisições para reduzir a agressividade das chamadas.

Compatibilidade

Compatível com ambientes Node.js que suportem:

• URLSearchParams
• async/await

Licença

MIT

MIT License

Copyright (c) 2026 Sebastião Jonas

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.