About

soundts is a small library for accessing SoundCloud API written in pure TypeScript and has zero dependencies.

Install

npm install soundts

Authorization

To get access to SoundCloud API follow the steps below:

• Open the page of creating a new application
• Fill the form and get back to your applications
• Save Client ID and Client Secret

So, Client ID and Client Secret are your credentials for authorization.

API Documentation

• OpenAPI
• Developers guide

Examples

Search for tracks, playlists, and users

import { Soundcloud, SoundcloudCredentials } from "soundts";

async function bootstrap() {
  const sc = new Soundcloud({
    credentials: new SoundcloudCredentials({
      clientId: process.env.CLIENT_ID!,
      clientSecret: process.env.CLIENT_SECRET!,
    }),
  });

  const tracksPaginator = await sc.tracks.search({
    q: "Wamentirele",
    limit: 2,
    access: ["playable"],
  });

  tracksPaginator.collection.forEach((track) =>
    console.log(`${track.user?.username} - ${track.title}`),
  );

  const playlistsPaginator = await sc.playlists.search({
    q: "DSBM",
    limit: 2,
    access: ["playable"],
  });

  playlistsPaginator.collection.forEach((playlist) =>
    console.log(`${playlist.user?.username} - ${playlist.title}`),
  );

  const usersPaginator = await sc.users.search({
    q: "User with good username",
    limit: 2,
  });

  usersPaginator.collection.forEach((user) => console.log(user.username));
}
bootstrap();

Get track, user or playlist by it's urn

import { Soundcloud, SoundcloudCredentials } from "soundts";

async function bootstrap() {
  const sc = new Soundcloud({
    credentials: new SoundcloudCredentials({
      clientId: process.env.CLIENT_ID!,
      clientSecret: process.env.CLIENT_SECRET!,
    }),
  });

  const track = await sc.tracks.getByUrn("soundcloud:tracks:1015448728");
  console.log(track.title);

  const user = await sc.users.getByUrn("soundcloud:users:948745750");
  console.log(user.username);

  const playlist = await sc.playlists.getByUrn(
    "soundcloud:playlists:1212781357",
  );
  console.log(playlist.title);
}
bootstrap();

Get stream of track or download it

import { createWriteStream } from "fs";
import { Soundcloud, SoundcloudCredentials } from "soundts";
import { pipeline } from "stream/promises";

async function bootstrap() {
  const sc = new Soundcloud({
    credentials: new SoundcloudCredentials({
      clientId: process.env.CLIENT_ID!,
      clientSecret: process.env.CLIENT_SECRET!,
    }),
  });

  const trackStream = await sc.tracks.stream(
    "soundcloud:tracks:441699126",
    "http_mp3_128_url",
  );

  const output = createWriteStream("6000000000себя.mp3");
  await pipeline(trackStream, output);
}
bootstrap();

Save and load credentials

import { createReadStream } from "fs";
import { Soundcloud, SoundcloudCredentials } from "soundts";

async function bootstrap() {
  const sc = new Soundcloud({
    credentials: new SoundcloudCredentials({
      clientId: process.env.CLIENT_ID!,
      clientSecret: process.env.CLIENT_SECRET!,
    }),
  });

  await sc.signIn();
  console.log(sc.credentials);

  const credentialsDump = sc.credentials.dump();

  try {
    const credentials = SoundcloudCredentials.load(credentialsDump);

    console.log(credentials);
  } catch (error) {
    console.error("Unable to load credentials from soundcloud.auth: ", error);
  }
}
bootstrap();