Navidrome API Client

A Node.js/Next.js client for interacting with Navidrome's Subsonic API, written in TypeScript.

Installation

npm install navidrome-ts-client

Usage

Basic Example

import Navidrome from 'navidrome-ts-client';

// Create a client instance
const navidrome = new Navidrome({
  serverUrl: 'https://your-navidrome-server.com',
  username: 'your_username',
  password: 'your_password',
  appName: 'MyMusicApp'  // Optional, defaults to 'NavidromeApi'
});

// Ping the server
async function checkConnection() {
  try {
    const response = await navidrome.system.ping();
    console.log('Connected to Navidrome server!');
    return true;
  } catch (error) {
    console.error('Failed to connect:', error);
    return false;
  }
}

// Get all artists
async function getAllArtists() {
  const response = await navidrome.browsing.getArtists();
  return response.subsonic.artists.index;
}

// Search for music
async function searchMusic(query) {
  const response = await navidrome.search.search3(query);
  return response.subsonic.searchResult3;
}

// Get album art URL
function getAlbumArt(albumId, size = 300) {
  return navidrome.media.getCoverArtUrl(albumId, size);
}

Next.js Example

// In a Next.js API route (pages/api/navidrome/search.ts)
import { NextApiRequest, NextApiResponse } from 'next';
import Navidrome from 'navidrome-ts-client';

// Create a client (consider using a singleton pattern)
const navidrome = new Navidrome({
  serverUrl: process.env.NAVIDROME_URL!,
  username: process.env.NAVIDROME_USER!,
  password: process.env.NAVIDROME_PASSWORD!,
  appName: 'MyNextjsApp'
});

export default async function handler(req: NextApiRequest, res: NextApiResponse) {
  const { query } = req.query;
  
  if (!query || typeof query !== 'string') {
    return res.status(400).json({ error: 'Query parameter is required' });
  }
  
  try {
    const searchResults = await navidrome.search.search3(query);
    return res.status(200).json(searchResults);
  } catch (error) {
    console.error('Error searching Navidrome:', error);
    return res.status(500).json({ error: 'Failed to search music' });
  }
}

API Documentation

The client is organized into different sections, mirroring the structure of the Subsonic API:

System

• system.ping() - Tests connectivity with the server
• system.getLicense() - Gets license details

Browsing

• browsing.getMusicFolders() - Gets all music folders
• browsing.getArtists() - Gets all artists
• browsing.getArtist(id) - Gets artist details
• browsing.getAlbum(id) - Gets album details
• browsing.getGenres() - Gets all genres
• And more...

Lists

• lists.getAlbumList2(type, ...) - Gets albums sorted in various ways
• lists.getRandomSongs(...) - Gets random songs
• lists.getStarred2() - Gets starred items
• And more...

Search

• search.search(query, ...) - Searches for artists, albums, and songs
• search.search3(query, ...) - Enhanced search with more metadata

Playlists

• playlists.getPlaylists() - Gets all playlists
• playlists.getPlaylist(id) - Gets playlist details
• playlists.createPlaylist(name, songIds) - Creates a playlist
• playlists.updatePlaylist(id, ...) - Updates a playlist
• playlists.deletePlaylist(id) - Deletes a playlist

Media

• media.getStreamUrl(options) - Gets URL for streaming a song
• media.getDownloadUrl(id) - Gets URL for downloading content
• media.getCoverArtUrl(id, size) - Gets URL for cover art
• media.getLyrics(artist, title) - Gets lyrics for a song
• media.scrobble(params) - Records that a song was played
• media.star(params) - Stars an item
• media.unstar(params) - Unstars an item
• media.setRating(id, rating) - Sets rating for an item

License

MIT