Fync
Providers

Spotify

Control Spotify playback, manage playlists, and access music catalog

Spotify API

Quick Setup

import { Spotify } from '@remcostoeten/fync';
const spotify = Spotify({ token: process.env.SPOTIFY_TOKEN! });

Music Catalog

Tracks & Albums

// Get track info and audio features
const track = await spotify.getTrack('4iV5W9uYEdYUVa79Axb7Rh');
const features = await spotify.getAudioFeatures('4iV5W9uYEdYUVa79Axb7Rh');

// Get album and its tracks
const album = await spotify.getAlbum('1DFixLWuPkv3KT3TnV35m3');
const albumTracks = await spotify.getAlbumTracks('1DFixLWuPkv3KT3TnV35m3');

// Artist info and top tracks
const artist = await spotify.getArtist('4Z8W4fKeB5YxbusRsdQVPb');
const topTracks = await spotify.getArtistTopTracks('4Z8W4fKeB5YxbusRsdQVPb');
// Search by type
const searchResults = await spotify.search('Drake', ['track', 'artist']);

// Convenience search methods
const tracks = await spotify.searchTracks('Drake');
const artists = await spotify.searchArtists('Drake');
const albums = await spotify.searchAlbums('Scorpion');
const playlists = await spotify.searchPlaylists('rap');

📼 Playlist Management

Basic Playlist Operations

// Get playlist details and tracks
const playlist = await spotify.getPlaylist('37i9dQZF1DXcBWIGoYBM5M');
const tracks = await spotify.getPlaylistTracks('37i9dQZF1DXcBWIGoYBM5M');

// Create a new playlist
const newPlaylist = await spotify.createPlaylist('user_id', 'My Jamz', {
  description: 'My favorite tracks',
  public: false
});

Track Management

// Add tracks to playlist
await spotify.addTracksToPlaylist('playlistId', [
  'spotify:track:4iV5W9uYEdYUVa79Axb7Rh',
  'spotify:track:5U2Wd7q3gXUbPDjXEAP0BM'
]);

// Remove tracks from playlist
await spotify.removeTracksFromPlaylist('playlistId', [
  'spotify:track:4iV5W9uYEdYUVa79Axb7Rh'
]);

// Reorder tracks in playlist
await spotify.reorderPlaylistTracks('playlistId', 0, 5); // Move track 0 to position 5

// Replace all tracks in playlist
await spotify.replacePlaylistTracks('playlistId', [
  'spotify:track:5U2Wd7q3gXUbPDjXEAP0BM'
]);

🎧 Player Control

Basic Playback

// Play a specific track
await spotify.playTrack('spotify:track:4iV5W9uYEdYUVa79Axb7Rh');

// Control playback
await spotify.play();
await spotify.pausePlayback();
await spotify.skipToNext();
await spotify.skipToPrevious();

// Get current state
const currentlyPlaying = await spotify.getCurrentlyPlaying();
const playbackState = await spotify.getCurrentPlayback();

Advanced Playback Control

// Seek to position
await spotify.seek(30000); // 30 seconds

// Volume and repeat
await spotify.setVolume(50); // 0-100
await spotify.setRepeatMode('track'); // 'off', 'track', 'context'
await spotify.setShuffle(true);

// Get available devices
const devices = await spotify.getDevices();

👤 User Data

Profile & Library

// Current user info
const user = await spotify.getCurrentUser();
const topTracks = await spotify.getMyTopTracks({ limit: 20 });
const topArtists = await spotify.getMyTopArtists({ limit: 20 });

// Recently played
const recent = await spotify.getRecentlyPlayed({ limit: 50 });

// User's playlists
const myPlaylists = await spotify.getUserPlaylists();

Save & Follow

// Save tracks to "Your Library"
await spotify.saveTracks(['trackId1', 'trackId2']);
await spotify.removeSavedTracks(['trackId1', 'trackId2']);

// Follow artists
await spotify.followArtists(['artistId1', 'artistId2']);
await spotify.unfollowArtists(['artistId1']);

// Follow playlists
await spotify.followPlaylist('playlistId');
await spotify.unfollowPlaylist('playlistId');

Browse & Discover

// Featured playlists
const featured = await spotify.getFeaturedPlaylists();

// Browse categories
const categories = await spotify.getCategories();
const categoryPlaylists = await spotify.getCategoryPlaylists('rock');

// Get recommendations
const recommendations = await spotify.getRecommendations({
  seed_artists: '4Z8W4fKeB5YxbusRsdQVPb',
  seed_genres: 'pop',
  min_energy: 0.8
});

📋 Quick Reference

CategoryKey Methods
TracksgetTrack(), getAudioFeatures(), searchTracks()
AlbumsgetAlbum(), getAlbumTracks(), searchAlbums()
ArtistsgetArtist(), getArtistTopTracks(), searchArtists()
PlaylistsgetPlaylist(), createPlaylist(), addTracksToPlaylist()
PlayerplayTrack(), pausePlayback(), getCurrentlyPlaying()
UsergetCurrentUser(), getMyTopTracks(), getUserPlaylists()
BrowsegetFeaturedPlaylists(), getRecommendations()