마음을 읽는 음악 API 구축: Node.js를 사용한 AI 기반 무드 플레이리스트 생성기

"방금 차였고 비가 내린다"고 입력하면 당신의 기분과 완벽하게 일치하는 맞춤형 플레이리스트를 즉시 받는다고 상상해보세요. 오늘 우리는 텍스트에서 인간의 감정을 읽고 AI 감정 분석을 사용해 맞춤형 Spotify 플레이리스트를 생성하는 API를 구축할 것입니다. 이것은 단순히 또 다른 튜토리얼이 아닙니다. 우리는 사람들의 하루를 정말로 개선할 수 있는 무언가를 만들고 있습니다.

필요한 것들

설치된 Node.js (nodejs.org)
Spotify 개발자 계정 (developer.spotify.com에서 무료)
코드 에디터 - VS Code를 사용하겠지만, 익숙한 코드 에디터가 있다면 사용해도 되고, 그렇지 않으면 여기서 VS Code를 다운로드할 수 있습니다: https://code.visualstudio.com/
OpenAI API 키 (또는 무료 감정 분석 라이브러리를 사용합니다)
JavaScript 기초 지식
단 30분의 시간

Node.js 다운로드 및 설치

nodejs.org로 이동

Get Node.js 클릭

페이지를 'Or get a prebuilt Node.js'까지 스크롤

사전 빌드된 설치 프로그램이 특히 초보자에게는 최고의 선택입니다:

30분 이상의 컴파일 대신 2분 설정
수백만 명에 의해 테스트되어 작동이 보장됨
더 빨리 코딩을 시작할 수 있음

운영체제(Windows, macOs, Linux 또는 AIX)를 선택

다운로드 버튼을 클릭(버튼 텍스트는 Windows Installer (.msi), macOs (.pkg), Linux (.xz) 또는 Standalone Binary (.gz)가 됩니다)

다운로드 후 설치 프로그램을 열고 다음 설치 단계를 따르세요:

1단계: 환영 화면

다운로드한 설치 프로그램 파일을 더블 클릭하여 설치 프로세스를 시작합니다. Node.js Setup Welcome 화면이 표시됩니다.

"Next"를 클릭하여 계속합니다.

2단계: 라이센스 계약

라이센스 계약을 읽으세요 (또는 빠르게 스크롤하세요 - 표준 오픈 소스 라이센스입니다).

"I accept the terms in the License Agreement" 체크박스를 체크하세요.

"Next"를 클릭하여 진행합니다.

3단계: 설치 위치 선택

기본 설치 경로를 유지하세요 (보통 Windows에서는 C:\Program Files\nodejs\).

다른 곳에 설치할 특별한 이유가 없다면 아무것도 변경하지 마세요.

"Next"를 클릭하여 계속합니다.

4단계: 구성 요소 선택

모든 체크박스를 선택된 상태로 두세요 (Node.js 런타임, npm 패키지 매니저, 온라인 문서 바로가기, Add to PATH).

"Add to PATH" 옵션이 중요합니다 - 이를 통해 모든 명령 프롬프트나 터미널에서 Node.js를 실행할 수 있습니다.

"Next"를 클릭하여 계속합니다.

5단계: 네이티브 모듈용 도구 (중요 - 건너뛰지 마세요!)

⚠️ 중요: 이 박스에 반드시 체크해야 합니다!

"Automatically install the necessary tools"에 체크하지 않으면 Node.js가 많은 패키지에서 제대로 작동하지 않습니다. 이 단계는 튜토리얼이 작동하는 데 필수적입니다!

✅ "Automatically install the necessary tools" 체크박스를 체크하세요.

이는 Python과 Visual Studio Build Tools를 설치하며, 많은 npm 패키지가 네이티브 코드를 제대로 컴파일하는 데 필요합니다.

"Next"를 클릭하여 계속합니다.

💡 이 체크박스가 중요한 이유:

많은 npm 패키지가 네이티브 코드 컴파일을 필요로 하며 이 도구들 없이는 작동하지 않습니다
이 도구들 없이는 패키지를 설치할 때 암호 같은 오류 메시지를 받게 됩니다
개발 여정에서 나중에 몇 시간의 문제 해결을 절약해 줍니다

6단계: 설치 준비 완료

설치 설정을 마지막으로 검토하세요.

"Install"을 클릭하여 설치 프로세스를 시작합니다.

참고: Windows 사용자 계정 컨트롤 프롬프트가 표시될 수 있습니다 - 설치를 허용하려면 "예"를 클릭하세요.

7단계: 설치 완료

설치가 완료되기를 기다리세요 - 보통 1-2분 정도 걸립니다.

설치가 완료되면 "Finish"를 클릭하세요.

8단계: 추가 도구 설치 (5단계에서 박스에 체크한 경우)

5단계에서 "automatically install tools" 옵션에 체크했다면 다음과 같은 명령 프롬프트 창이 나타날 것입니다:

👆 아무 키나 눌러 설치 프로세스를 시작하세요

다음에 일어나는 일:

프롬프트가 보이면 아무 키나 누르고 Python과 Visual Studio Build Tools 설치를 시작하세요
10-15분 동안 참을성 있게 기다리세요 - 이는 많은 npm 패키지에 필요한 개발 도구를 설치합니다
많은 텍스트가 스크롤되는 것이 보일 것입니다 - 정상입니다! 창을 닫지 마세요
설치가 완료되면 ENTER를 눌러 설치 프로그램을 종료하세요

다시 아무 키나 클릭하세요...앱이 PC에 변경을 가하도록 허용할 것인지 묻는 또 다른 팝업이 표시될 것입니다. 계속해서 예를 클릭하여 설치를 진행하세요. 그러면 다음과 같은 것이 표시되어야 합니다:

📦 빌드 도구 설치 중 - 10-15분 정도 걸릴 수 있습니다

설치가 완료되기를 기다린 다음 지시에 따라 터미널 하단에 ENTER를 입력하고 키보드의 enter 버튼을 눌러 종료하세요:

개발 환경 설정

이제 재미있는 부분으로 넘어가서 앱을 생생하게 만들 수 있습니다. 먼저 코드 에디터를 여세요. VS Code를 사용하겠지만, 다른 것에 더 익숙하지 않다면 이 튜토리얼을 쉽게 따라할 수 있도록 VS Code를 사용하는 것을 권장합니다.

터미널을 여세요. 방법을 모르신다면, 코드 에디터 상단의 3개 점을 클릭하고 'Terminal'까지 스크롤한 다음 커서를 올리고 'New Terminal'을 클릭하세요.

터미널에 다음 4개 명령어를 하나씩 입력하세요:

mkdir mood-music-api
cd mood-music-api
npm init -y
npm install express axios sentiment dotenv spotify-web-api-node

명령어 분석: 각 단계가 실제로 무엇을 하는지

1. mkdir mood-music-api

수행 작업:

"mood-music-api"라는 이름의 새로운 빈 폴더 생성
mkdir = "make directory" (디렉터리 만들기)

필요한 이유:

프로젝트에는 자체 홈/작업공간이 필요
코드를 정리하고 다른 프로젝트와 분리
각 학교 과제를 위해 새 폴더를 만드는 것과 같음

2. cd mood-music-api

수행 작업:

터미널/명령 프롬프트를 해당 폴더 안으로 이동
cd = "change directory" (디렉터리 변경)

필요한 이유:

향후 모든 명령어는 프로젝트 폴더 내에서 실행됨
문서를 저장하기 전에 특정 폴더를 여는 것과 같음

3. npm init -y

수행 작업:

기본 설정으로 package.json 파일 생성
package.json은 프로젝트의 신분증과 쇼핑 목록 같은 것

필요한 이유:

Node.js에게 이 폴더가 Node.js 프로젝트라고 알려줌
프로젝트에 필요한 라이브러리(패키지)를 추적
이름, 버전, 설명 등의 프로젝트 정보를 저장

4. npm install express axios sentiment dotenv spotify-web-api-node

수행 작업:

프로젝트에 필요한 5가지 다른 코드 라이브러리를 다운로드하고 설치
수천 개의 파일이 있는 node_modules 폴더 생성
이러한 의존성을 기억하도록 package.json 업데이트

각 라이브러리의 역할:

express: API 요청을 처리하는 웹 서버 생성
axios: 다른 API(Spotify 등)에 HTTP 요청 생성
sentiment: 텍스트를 분석하여 감정/기분 감지
dotenv: 비밀 API 키를 안전하게 저장
spotify-web-api-node: Spotify에 연결하여 음악 데이터 가져오기

이제 파일 → 폴더 열기로 가서 mood-music-api라는 폴더를 검색하여 열어 폴더를 여세요.

탐색기에서 node modules, package-lock.json, package.json 파일이 있는 Mood-MUSIC-API라는 폴더가 표시되어야 합니다.

Spotify API 키 가져오기 (단계별)

이제 새 파일을 만들어 .env라고 이름을 지으려고 합니다. 이를 위해 File을 클릭한 다음 New File을 클릭하고 .env를 입력한 다음 enter를 누르고 파일 이름을 다시 .env로 입력하고 Create File을 클릭하면 됩니다.

이 파일에 무엇인가를 입력하기 전에 API 키를 가져와야 합니다.

1단계: Spotify 개발자 계정 생성

방문: developer.spotify.com

보이는 것:

우측 상단의 "Log in" 링크
Spotify가 없다면: "Sign up"을 클릭 (무료입니다!)
Spotify가 있다면: 기존 계정 사용

중요: Spotify Premium이 필요하지 않습니다 - 무료 계정도 API 액세스에는 문제없이 작동합니다!

2단계: 앱 생성

로그인 후:

"Create app"을 클릭

양식을 작성:

App name: Mood Music API
App description: AI-powered mood playlist generator
Website: http://localhost:3000 (현재는)
Redirect URI: https://localhost:3000/callback

사용할 예정인 API는?

✅ "Web API"에 체크
✅ "Web Playback SDK"에 체크 (선택사항, 미래 기능용)

약관에 동의하고 "Save"를 클릭

3단계: 비밀 키 가져오기

앱을 생성한 후:

앱 대시보드가 표시됩니다
Basic Information 아래에 두 가지 중요한 정보가 표시됩니다:

Client ID: abc123def456... (표시됨, 32자)
Client Secret: [Show client secret] (클릭하여 표시)

"Show client secret"을 클릭하여 비밀 키를 표시
두 키를 모두 복사 - 다음 단계에서 필요합니다!

이 키들의 역할:

Client ID: 앱의 공개 식별자 (사용자명과 같음)
Client Secret: 앱의 비밀번호 (비밀로 유지하세요!)

4단계: 키를 프로젝트에 추가

생성한 .env 파일에 키를 추가:

SPOTIFY_CLIENT_ID=your_actual_client_id_here
SPOTIFY_CLIENT_SECRET=your_actual_client_secret_here
PORT=3000

ctrl + s 또는 cmd + s 또는 File → save를 클릭하여 변경사항을 저장하세요.

5단계: 비밀 보호

중요: Client Secret을 공개하지 마세요!

터미널에서 다음 명령어를 사용하여 .gitignore 파일에 .env를 추가:

# .gitignore 파일 생성
# 또는 macOS/Linux에서
touch .gitignore

# 또는 PowerShell
New-Item -Path ".gitignore" -ItemType "file"
# 또는 더 간단히: 
echo $null > .gitignore

# .gitignore에 이 줄을 추가:
.env
node_modules/

ctrl + s 또는 cmd + s 또는 File → save를 클릭하여 변경사항을 저장하세요.

무드 감지 엔진

파일을 생성하고 moodAnalyzer.js라고 이름을 지으세요 - 여기서 마법이 일어납니다.

파일에 다음 코드를 추가하고 변경사항을 저장하세요.

const Sentiment = require('sentiment');
const sentiment = new Sentiment();

class MoodAnalyzer {
  analyzeMood(text) {
    const result = sentiment.analyze(text);
    
    // 컨텍스트 단서를 사용한 향상된 무드 감지
    const moodKeywords = {
      energetic: ['pumped', 'excited', 'energy', 'workout', 'party', 'dancing'],
      sad: ['dumped', 'broke up', 'crying', 'lonely', 'depressed', 'heartbreak'],
      angry: ['furious', 'pissed', 'angry', 'mad', 'rage', 'frustrated'],
      chill: ['relax', 'calm', 'peaceful', 'meditation', 'study', 'focus'],
      romantic: ['love', 'date', 'crush', 'valentine', 'romantic', 'kiss'],
      nostalgic: ['memories', 'throwback', 'old days', 'reminiscing', 'vintage']
    };
    
    const lowerText = text.toLowerCase();
    let detectedMood = 'neutral';
    let confidence = Math.abs(result.score);
    
    // 특정 무드 키워드 확인
    for (const [mood, keywords] of Object.entries(moodKeywords)) {
      if (keywords.some(keyword => lowerText.includes(keyword))) {
        detectedMood = mood;
        confidence += 2;
        break;
      }
    }
    
    // 감정 점수로 대체
    if (detectedMood === 'neutral') {
      if (result.score > 2) detectedMood = 'happy';
      else if (result.score < -2) detectedMood = 'sad';
      else if (result.score < 0) detectedMood = 'melancholy';
      else detectedMood = 'chill';
    }
    
    return {
      mood: detectedMood,
      confidence: Math.min(confidence, 10),
      sentiment: result.score,
      intensity: this.calculateIntensity(text, result.score)
    };
  }
  
  calculateIntensity(text, score) {
    const intensifiers = ['very', 'extremely', 'really', 'super', 'totally', '!!!', 'so much'];
    const hasIntensifiers = intensifiers.some(word => text.toLowerCase().includes(word));
    const baseIntensity = Math.abs(score) / 5;
    return Math.min((hasIntensifiers ? baseIntensity * 1.5 : baseIntensity), 1);
  }
}

module.exports = new MoodAnalyzer();

Spotify 플레이리스트 마법사

파일을 생성하고 playlistGenerator.js라고 이름을 지으세요. 그런 다음 다음 코드를 추가하고 변경사항을 저장하세요:

const SpotifyWebApi = require('spotify-web-api-node');

class PlaylistGenerator {
  constructor() {
    this.spotifyApi = new SpotifyWebApi({
      clientId: process.env.SPOTIFY_CLIENT_ID,
      clientSecret: process.env.SPOTIFY_CLIENT_SECRET
    });
    this.initializeSpotify();
  }
  
  async initializeSpotify() {
    try {
      console.log('🔑 Spotify 인증 시도 중...');
      console.log('Client ID:', process.env.SPOTIFY_CLIENT_ID ? 
        `${process.env.SPOTIFY_CLIENT_ID.substring(0, 8)}...` : '누락');
      console.log('Client Secret:', process.env.SPOTIFY_CLIENT_SECRET ? 
        `${process.env.SPOTIFY_CLIENT_SECRET.substring(0, 8)}...` : '누락');
      
      const data = await this.spotifyApi.clientCredentialsGrant();
      this.spotifyApi.setAccessToken(data.body['access_token']);
      console.log('🎵 Spotify 연결 성공!');
    } catch (error) {
      console.error('❌ Spotify 연결 실패:', error.message);
      console.error('상태 코드:', error.statusCode);
      console.error('이는 일반적으로 유효하지 않은 API 자격 증명을 의미합니다');
    }
  }
  
  // ... (문서에 표시된 나머지 코드)
}

module.exports = PlaylistGenerator;

마음 읽기 API 서버

파일을 생성하고 server.js라고 이름을 지은 다음, 다음 코드를 추가하고 변경사항을 저장하세요:

require('dotenv').config();
const express = require('express');
const moodAnalyzer = require('./moodAnalyzer');
const PlaylistGenerator = require('./playlistGenerator');

// 구 Node.js 버전용 node-fetch 추가
let fetch;
if (typeof globalThis.fetch === 'undefined') {
  console.log('📦 Node.js fetch를 사용할 수 없어 node-fetch 패키지 사용 중...');
  try {
    fetch = require('node-fetch');
  } catch (error) {
    console.error('❌ node-fetch를 설치해주세요: npm install node-fetch');
    process.exit(1);
  }
} else {
  fetch = globalThis.fetch;
  console.log('✅ 내장 Node.js fetch 사용 중');
}

const app = express();
const PORT = process.env.PORT || 3000;
const playlistGen = new PlaylistGenerator();

app.use(express.json());

// 아름다운 웹 인터페이스
app.get('/', (req, res) => {
  res.send(\`
    <!DOCTYPE html>
    <html>
    <head>
        <title>마음 읽기 음악 API</title>
        <style>
            /* 아름다운 그라디언트 스타일링과 사용자 정의 오디오 컨트롤 */
        </style>
    </head>
    <body>
        <div class="container">
            <h1>🧠🎵 마음 읽기 음악 API</h1>
            <p class="subtitle">기분을 알려주시면 당신의 무드에 완벽한 플레이리스트를 만들어드립니다!</p>
            
            <textarea id="moodText" placeholder="기분을 입력하세요..."></textarea>
            <button onclick="generatePlaylist()">🎧 내 플레이리스트 생성</button>
            
            <div id="result" style="display:none;" class="result">
                <!-- 결과가 여기에 나타납니다 -->
            </div>
        </div>
        
        <script>
            // 플레이리스트 생성 및 오디오 컨트롤을 위한 JavaScript
        </script>
    </body>
    </html>
  \`);
});

// 마법의 엔드포인트
app.post('/api/mood-playlist', async (req, res) => {
  // API 로직이 여기에
});

app.listen(PORT, () => {
  console.log(`🚀 마음 읽기 음악 API가 http://localhost:${PORT}에서 실행 중`);
  console.log('🧠 무드 분석 및 플레이리스트 생성 준비 완료!');
});

5단계: 감정 AI 테스트

서버를 시작하세요:

node server.js

다음과 같은 것이 표시되어야 합니다:

이제 웹 브라우저를 열고 위 이미지에 표시된 로컬 링크 (http://localhost:3000)로 가서 마음 읽기 음악 API를 테스트하세요!

피해야 할 일반적인 함정

Spotify API 제한: 무료 티어에는 속도 제한이 있습니다. 프로덕션 사용을 위해 응답을 캐시하고 재시도 로직을 구현하세요.
무드 오해석: 감정 분석을 혼동시킬 수 있는 풍자("좋아, 또 월요일...") 같은 엣지 케이스를 테스트하세요.
빈 플레이리스트: Spotify가 추천을 반환하지 않는 경우를 위해 대체 장르를 제공하여 항상 처리하세요.
API 키 노출: .env 파일을 커밋하지 마세요. 프로덕션에서는 환경 변수를 사용하세요.

다음 단계

이제 정말 멋진 것을 만들었습니다! 더 좋게 만드는 방법은 다음과 같습니다:

사용자 계정 추가: 무드 히스토리와 플레이리스트 선호도 저장
머신 러닝: 정확도 향상을 위해 사용자 피드백으로 커스텀 모델 훈련
소셜 기능: 사용자가 친구들과 무드 플레이리스트 공유 가능
음성 통합: 음성 무드 감지를 위해 speech-to-text API와 연결
웨어러블 통합: 더 깊은 무드 인사이트를 위해 심박수와 활동 데이터 읽기
배포 및 확장: 캐싱에 Redis 사용, 적절한 인증 구현

당신의 마음 읽기 음악 API는 이제 인간의 감정을 이해하고 완벽한 사운드트랙으로 응답할 수 있습니다. AI 감정 분석과 음악 큐레이션의 이러한 조합은 개인화된 경험의 미래를 나타냅니다. 가능성은 무한합니다!

이 앱을 더 발전시킬 다음 튜토리얼을 기대해 주세요...