spotify-api

Spotify Web API

Spotify Web API는 트랙·앨범·플레이리스트·아티스트 같은 음악 데이터를 조회하고, 인증된 사용자의 재생 상태를 가져오거나 재생을 제어할 수 있게 해 주는 RESTful API예요. 기본 주소는 https://api.spotify.com/v1이고, 앱을 만들고 접근 토큰(Access Token)을 받아서 Authorization: Bearer 헤더로 인증해요. 웹 애플리케이션에서 직접 음악을 재생·스트리밍하려면 Web Playback SDK(클라이언트 전용 JavaScript 라이브러리)를 함께 사용할 수 있어요.

출처: 문서

본문

핵심 기능

OAuth 인증: 모든 API 요청에 Bearer 토큰이 필요해요. 액세스 토큰은 1시간(3600초) 동안 유효하고, 만료되면 새로 발급받아야 해요. 인증 방식은 상황에 따라 여러 가지가 있는데, 주로 Client Credentials Flow(백엔드에서 앱 자격 증명만으로 토큰 발급), Authorization Code Flow(사용자 데이터 접근용), Authorization Code with PKCE(모바일/SPA용)를 사용해요.
데이터 조회(Read): 트랙·앨범·아티스트·플레이리스트·오디오 특징·추천 등 대부분의 음악 메타데이터를 조회할 수 있어요.
사용자 라이브러리/프로필: 현재 사용자 프로필(/me), 저장한 트랙·앨범, 팔로우 정보, 최근 재생 목록 등을 다룰 수 있어요.
재생 컨트롤(Player): 사용자의 Spotify 계정에서 재생 중인 콘텐츠 정보를 가져오고(Get Player's Currently Playing Track 등), 재생/일시정지, 다음/이전 곡, 시크(Seek), 볼륨, 셔플·반복, 재생 디바이스 전환 등을 제어할 수 있어요. 단, 재생 제어는 Spotify Premium 구독(모바일 전용 프리미엄 제외)이 필요해요.
Playback SDK: 웹사이트 안에서 라디오 같은 로컬 Spotify Connect 디바이스를 만들어 직접 음악을 스트리밍하고 컨트롤하는 클라이언트 전용 JavaScript 라이브러리예요. Chrome·Firefox·Safari·Edge에서 지원되며, 현재 재생 상태 메타데이터도 얻을 수 있어요.

OAuth 인증 예시

Client Credentials Flow는 앱 시크릿만으로 서버 간 토큰을 받을 때 사용해요. 먼저 Spotify Developer Dashboard에서 앱을 만들고 client_id와 client_secret을 발급받아요.

curl -X POST "https://accounts.spotify.com/api/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET"

응답에서 access_token을 받아 이후 모든 요청의 Authorization 헤더에 넣어요.

트랙/플레이리스트 조회 예시

공식 문서가 제공하는 Get a track 엔드포인트 cURL 예시예요.

curl --request GET \
  'https://api.spotify.com/v1/tracks/2TpxZ7JUBn3uw46aR7qd6V' \
  --header "Authorization: Bearer ***"

플레이리스트는 https://api.spotify.com/v1/playlists/{playlist_id}로 조회하고, GET /playlists/{playlist_id}/tracks로 포함된 트랙 목록(페이징 응답)을 가져올 수 있어요. 액세스 토큰을 가진 사용자의 프로필은 https://api.spotify.com/v1/me로 조회해요.

async function getProfile(accessToken) {
  const response = await fetch('https://api.spotify.com/v1/me', {
    headers: {
      Authorization: 'Bearer ' + accessToken
    }
  });
  const data = await response.json();
  return data;
}

SDK 설치

Web Playback SDK는 HTML에서 스크립트 태그로 로드해요.

<script src="https://sdk.scdn.co/spotify-player.js"></script>

Web API를 더 편리하게 쓰는 오픈소스 클라이언트 라이브러리로는 Python의 spotipy와 JavaScript의 spotify-web-api-node가 있어요.

pip install spotipy

npm install spotify-web-api-node

Web Playback SDK 사용 예시

웹 앱에서 플레이어를 만들어 로컬 Spotify Connect 디바이스로 등록하고, player.activateElement()로 활성화해서 재생을 시작하는 기본 흐름이에요.

const player = new Spotify.Player({
  name: 'Web Playback SDK',
  getOAuthToken: (cb) => { cb(access_token); },
  volume: 0.5
});

player.addListener('ready', ({ device_id }) => {
  console.log('Ready with Device ID', device_id);
  // device_id를 백엔드로 전달해 재생 제어(Transfer/Resume)에 사용
});

player.connect();

플레이어는 connect, pause, resume, seek, previousTrack, nextTrack, getCurrentState 같은 메서드를 제공하고, player_state_changed 이벤트로 현재 재생 상태를 받아요. Web API의 Player 엔드포인트(GET /v1/me/player/currently-playing, PUT /v1/me/player/play 등)와 함께 쓰면 재생 컨트롤을 완성할 수 있어요.

더 알아보기 (Learn more)

공식 문서