explodingcamera / subsonic-api

typescript/javascript library for interacting with subsonic-compatible apis

Subsonic-API

A simple API library for interacting with Subsonic-compatible servers (Up to API version 1.16.1) written in TypeScript. Supports Node.js >= 18, bun >= 1 and modern Browsers. No dependencies and less than 4kb minified and gzipped.

Installation

$ npm install subsonic-api

Example Usage

You can also try out the example on CodeSandbox here.

import { SubsonicAPI } from "subsonic-api";

const api = new SubsonicAPI({
  url: "https://demo.navidrome.org",
  type: "navidrome", // or "generic" or "subsonic"
});

await api.login({
  username: "demo",
  password: "demo",
});

const { randomSongs } = await api.getRandomSongs();
console.log(randomSongs);

API

subsonic-api supports all of the Subsonic API methods as documented here, up to API version 1.16.1 / Subsonic 6.1.4. All methods return a promise that resolves to the JSON response from the server.

Additionally, the following methods are available:

login

login(options: LoginOptions): Promise<void>

Logs in to the server and stores the password for future requests.

interface LoginOptions {
  username: string;
  password: string;
}

navidromeSession

subsonicSession(): Promise<SessionInfo>

Creates a new Navidrome session

interface SessionInfo {
  id: string;
  isAdmin: boolean;
  name: string;
  subsonicSalt: string;
  subsonicToken: string;
  token: string;
  username: string;
}

baseURL

baseURL(): string

Returns the base URL of the server. Useful for interacting with other APIs like Navidrome's.

custom

custom(method: string, params: Params): Promise<Response>

Allows you to make a custom request to the server.

customJSON

customJSON<T>(method: string, params: Params): Promise<T>

Allows you to make a custom request to the server and parse the response as JSON.