A lightweight Subsonic and OpenSubsonic client for TypeScript. Supports Node.js, Deno, Bun, and modern browsers.
- Supports all Subsonic API methods up to version 1.16.1 / Subsonic 6.1.4.
- Supports OpenSubsonic extensions.
- Supports both GET and POST requests.
- Has zero runtime dependencies.
npm install subsonic-api
# or
bun add subsonic-api<script type="module"> import { SubsonicAPI } from "https://esm.sh/subsonic-api"; </script>
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);
subsonic-api supports all Subsonic API methods through API version 1.16.1 / Subsonic 6.1.4, along with the currently published OpenSubsonic extensions.
All methods return a promise that resolves to the JSON response from the server.
See the JSDoc documentation for a complete list of supported methods and their parameters.
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 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?: typeof fetch; // The crypto implementation to use. If not provided, the global WebCrypto object // or the Node.js crypto module will be used. crypto?: Crypto; }
baseURL(): string
Returns the base URL of the server. This is useful when interacting with other APIs exposed by the server.
const coverArtURL = await api.getCoverArtURL({ id: "cover-art-id", size: 512 }); const streamURL = await api.streamURL({ id: "song-id", maxBitRate: 320 });
Returns authenticated GET URLs without making a request. These methods are useful when passing a URL to native image or media components, and they work even when the client is configured with post: true.
The returned URLs contain authentication credentials and should be treated as sensitive.
custom(method: string, params: Params): Promise<Response>
Allows you to make a custom request to the server.
customJSON<T>(method: string, params: Params): Promise<T>
Allows you to make a custom request to the server and parse the response as JSON.