Subsonic-API

A lightweight Subsonic/Opensubsonic Client written in TypeScript. Supports Node, Deno, Bun, and modern Browsers.

Features

• Supports all Subsonic API methods up to version 1.16.1 / Subsonic 6.1.4.
• Supports most of OpenSubsonic's new API methods.
• Supports both GET and POST requests.

Installation

$ npm install subsonic-api  # npm
$ bun add subsonic-api      # bun

<script type="module">
  import { SubsonicAPI } from "https://esm.sh/subsonic-api";
</script>

Example Usage

import { SubsonicAPI } from "subsonic-api";

const api = new SubsonicAPI({
  url: "https://demo.navidrome.org",
  auth: {
    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. Additionally, most of OpenSubsonic's new API methods are also supported. All methods return a promise that resolves to the JSON response from the server.

Additionally, the following methods are available:

new SubsonicAPI

new SubsonicAPI(config: SubsonicConfig)

Creates a new SubsonicAPI instance.

interface SubsonicConfig {
  // The base URL of the Subsonic server, e.g., https://demo.navidrome.org.
  url: string;

  // The authentication details to use when connecting to the server.
  auth:
    | {
        username: string;
        password: string;
      }
    | {
        // See https://opensubsonic.netlify.app/docs/extensions/apikeyauth/
        apiKey: string;
      };

  // A salt to use when hashing the password. Not used if `auth.apiKey` is provided.
  salt?: string;

  // Whether to reuse generated salts. If not provided,
  // a random salt will be generated for each request.
  // Ignored if `salt` is provided or `auth.apiKey` is used.
  reuseSalt?: boolean;

  // Whether to use a POST requests instead of GET requests.
  // Only supported by OpenSubsonic compatible servers with the `formPost` extension.
  post?: boolean;

  // The fetch implementation to use. If not provided, the global fetch will be used.
  fetch?: Fetch;

  // The crypto implementation to use. If not provided, the global WebCrypto object
  // or the Node.js crypto module will be used.
  crypto?: WebCrypto;
}

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.