https://github.com/explodingcamera/subsonic-api
typescript/javascript library for interacting with subsonic-compatible apis
https://github.com/explodingcamera/subsonic-api
airsonic navidrome subsonic
Last synced: 6 months ago
JSON representation
typescript/javascript library for interacting with subsonic-compatible apis
- Host: GitHub
- URL: https://github.com/explodingcamera/subsonic-api
- Owner: explodingcamera
- License: mit
- Created: 2022-10-10T22:12:09.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2024-10-05T21:16:16.000Z (8 months ago)
- Last Synced: 2024-10-31T21:36:37.636Z (7 months ago)
- Topics: airsonic, navidrome, subsonic
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/subsonic-api
- Size: 742 KB
- Stars: 12
- Watchers: 2
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
# 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
```bash
$ npm install subsonic-api # npm
$ bun add subsonic-api # bun
```
```html
import { SubsonicAPI } from "https://esm.sh/subsonic-api";
```
## Example Usage
```ts
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](http://www.subsonic.org/pages/api.jsp), up to API version 1.16.1 / Subsonic 6.1.4. Additionally, most of [OpenSubsonic's new API methods](https://opensubsonic.netlify.app/) 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`
```ts
new SubsonicAPI(config: SubsonicConfig)
```
Creates a new SubsonicAPI instance.
```ts
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;
}
```
### `navidromeSession`
```ts
subsonicSession(): Promise
```
Creates a new Navidrome session
```ts
interface SessionInfo {
id: string;
isAdmin: boolean;
name: string;
subsonicSalt: string;
subsonicToken: string;
token: string;
username: string;
}
```
### `baseURL`
```ts
baseURL(): string
```
Returns the base URL of the server. Useful for interacting with other APIs like Navidrome's.
### `custom`
```ts
custom(method: string, params: Params): Promise
```
Allows you to make a custom request to the server.
### `customJSON`
```ts
customJSON(method: string, params: Params): Promise
```
Allows you to make a custom request to the server and parse the response as JSON.