@ted-dev/sc-info

Módulo Node.js enxuto para buscar informações públicas de faixas do SoundCloud. O pacote retorna imagem, imagem original/HD quando disponível, título, artista, links, descrição, likes, comentários, reproduções, duração e outros metadados básicos.

Este pacote não baixa MP3, não acessa streams e não faz conversão de áudio.

Instalação

npm install @ted-dev/sc-info

Node.js 18 ou superior.

Link público sem token

import SoundCloudInfo from '@ted-dev/sc-info';

const dados = await SoundCloudInfo.getPublicMetadataWithFallback(
  'https://soundcloud.com/artista/faixa'
);

console.log({
  titulo: dados.title,
  artista: dados.artist,
  link: dados.sourceUrl,
  imagem: dados.artworkUrl,
  imagemHd: dados.artworkUrlHd,
  descricao: dados.description,
  likes: dados.likesCount,
  comentarios: dados.commentCount,
  reproducoes: dados.playbackCount,
  duracaoMs: dados.durationMs
});

O método público tenta três fontes em sequência: oEmbed, metatags Open Graph e dados incorporados na página. O pacote não baixa conteúdo de áudio.

Com busca por nome

A busca por nome usa a API oficial e requer clientId ou accessToken:

const sc = new SoundCloudInfo({
  clientId: process.env.SOUNDCLOUD_CLIENT_ID,
  accessToken: process.env.SOUNDCLOUD_ACCESS_TOKEN
});

const resultado = await sc.searchBestMatch('Nâo Deixe o Nosso Amor Morrer', {
  limit: 3,
  maxAttempts: 10
});

for (const [index, faixa] of resultado.results.entries()) {
  console.log(`Resultado ${index + 1}`, {
    titulo: faixa.title,
    link: faixa.permalink_url,
    pontuacao: faixa.matchScore
  });
}

A busca executa até dez consultas sequenciais com variações de acentuação, pontuação, termos e qualificadores; combina e deduplica os resultados, e os ordena pela semelhança do título. Uma consulta que falhar não interrompe as demais: attempts registra cada tentativa e errors contém falhas, enquanto os resultados parciais são preservados. Se todas as consultas falharem, lança SoundCloudError. Para reduzir o volume, use maxAttempts (de 1 a 10; padrão 10). Sem credenciais, use um link público.

Busca pública sem credenciais

Sem credenciais da API, o módulo pode abrir a busca pública do SoundCloud para você escolher a faixa. A escolha é manual; não há extração automatizada dos resultados da página. Depois de copiar o link público da faixa, o módulo obtém os metadados pelo oEmbed/fallback.

import SoundCloudInfo from '@ted-dev/sc-info';

const busca = SoundCloudInfo.getPublicSearchUrl('Então Não Brinca');
console.log(busca); // abra o link e escolha a faixa correta

const dados = await SoundCloudInfo.getPublicMetadataWithFallback(
  'https://soundcloud.com/artista/faixa' // link escolhido na busca
);
console.log({ titulo: dados.title, artista: dados.artist, id: dados.trackId });

Este método não substitui searchBestMatch: não devolve automaticamente uma lista ranqueada pelo nome.

Informações retornadas

Os campos mais comuns são:

• title, description e artist;
• sourceUrl, permalinkUrl, artistUrl e trackId;
• artworkUrl para a miniatura;
• artworkUrlHd para a variante original do CDN, quando existir;
• likesCount, commentCount, playbackCount e downloadCount;
• durationMs, publishedAt, genre e license.

A variante artworkUrlHd depende de o arquivo original ainda estar disponível no CDN do SoundCloud. O módulo não aumenta artificialmente a resolução.

API

• new SoundCloudInfo({ clientId, accessToken, baseUrl, fetchImpl })
• search(query, options)
• searchBestMatch(query, options)
• resolve(url)
• getTrack(id)
• getTrackDetails(trackOrId)
• getComments(id, options)
• SoundCloudInfo.getPublicMetadata(url)
• SoundCloudInfo.getPublicMetadataWithFallback(url)

Licença

MIT.