A lightweight Subsonic/Opensubsonic Client written in TypeScript. Supports Node, Deno, Bun, and modern Browsers.
- 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.
$ npm install subsonic-api # npm
$ bun add subsonic-api # bun<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 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(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;
};
// A salt to use when hashing the password
salt?: string;
// Whether to reuse generated salts. If not provided,
// a random salt will be generated for each request.
// Ignored if `salt` is provided.
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;
}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(): stringReturns the base URL of the server. Useful for interacting with other APIs like Navidrome's.
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.