بناء واجهة برمجة تطبيقات الموسيقى القارئة للأذهان: مولد قوائم التشغيل المدعوم بالذكاء الاصطناعي باستخدام Node.js

تخيل أن تكتب "لقد انفصلت للتو وهناك مطر" وتحصل فوراً على قائمة تشغيل مخصصة بشكل مثالي تتناسب مع مشاعرك. اليوم، نحن ننشئ واجهة برمجة تطبيقات تقرأ المشاعر الإنسانية من النص وتولد قوائم تشغيل Spotify مخصصة باستخدام تحليل المشاعر بالذكاء الاصطناعي. هذا ليس مجرد برنامج تعليمي آخر. نحن نصنع شيئاً يمكن أن يحسن أيام الناس حقاً.

ما تحتاجه

Node.js مثبت (nodejs.org)
حساب مطور Spotify (مجاني على developer.spotify.com)
محرر الكود - سأستخدم VS Code لكن يمكنك استخدام محرر الكود الخاص بك إذا كان لديك واحد معتاد عليه وإلا يمكنك تنزيل VS Code هنا: https://code.visualstudio.com/
مفتاح واجهة برمجة تطبيقات OpenAI (أو سنستخدم مكتبة تحليل المشاعر المجانية)
معرفة أساسية بـ JavaScript
30 دقيقة فقط من وقتك

تنزيل وتثبيت Node.js

اذهب إلى nodejs.org

انقر على Get Node.js

قم بالتمرير لأسفل الصفحة إلى 'Or get a prebuilt Node.js'

مثبت مبني مسبقاً هو الخيار الأفضل خاصة للمبتدئين لأن:

إنه إعداد لمدة دقيقتين بدلاً من أكثر من 30 دقيقة للتجميع
مضمون للعمل وتم اختباره من قبل الملايين
يمكنك البدء في البرمجة بسرعة أكبر

حدد نظام التشغيل الخاص بك، Windows أو macOs أو Linux أو AIX

وانقر على زر التنزيل (سيحتوي على Windows Installer (.msi) أو macOs (.pkg) أو Linux (.xz) أو Standalone Binary (.gz) كنص الزر)

بمجرد التنزيل، افتح المثبت واتبع خطوات التثبيت التالية:

الخطوة 1: شاشة الترحيب

انقر نقراً مزدوجاً على ملف المثبت المنزل لبدء عملية التثبيت. ستظهر شاشة ترحيب Node.js Setup.

انقر على "Next" للمتابعة.

الخطوة 2: اتفاقية الترخيص

اقرأ اتفاقية الترخيص (أو تمرر خلالها بسرعة - إنها ترخيص المصدر المفتوح القياسي).

ضع علامة في خانة الاختيار "I accept the terms in the License Agreement".

انقر على "Next" للمتابعة.

الخطوة 3: اختيار موقع التثبيت

احتفظ بمسار التثبيت الافتراضي (عادة C:\Program Files\nodejs\ على Windows).

لا تغير أي شيء إلا إذا كان لديك سبب محدد للتثبيت في مكان آخر.

انقر على "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" للمتابعة.

أدوات Node.js الإضافية - يجب وضع علامة في مربع الاختيار

💡 لماذا هذا المربع بالغ الأهمية:

العديد من حزم npm تحتاج إلى تجميع كود أصلي ولن تعمل بدون هذه الأدوات
بدون هذه الأدوات، ستحصل على رسائل خطأ غامضة عند تثبيت الحزم
هذا يوفر لك ساعات من استكشاف الأخطاء لاحقاً في رحلة التطوير الخاصة بك

الخطوة 6: جاهز للتثبيت

راجع إعدادات التثبيت مرة أخيرة.

انقر على "Install" لبدء عملية التثبيت.

ملاحظة: قد ترى مطالبة تحكم حساب مستخدم Windows - انقر على "نعم" للسماح بالتثبيت.

الخطوة 7: التثبيت مكتمل

انتظر اكتمال التثبيت - عادة ما يستغرق 1-2 دقيقة.

انقر على "Finish" عند اكتمال التثبيت.

الخطوة 8: تثبيت أدوات إضافية (إذا وضعت علامة في المربع في الخطوة 5)

إذا وضعت علامة على خيار "automatically install tools" في الخطوة 5، ستظهر نافذة موجه أوامر مثل هذه:

👆 اضغط على أي مفتاح لبدء عملية التثبيت

ما يحدث بعد ذلك:

اضغط على أي مفتاح عندما ترى المطالبة لبدء تثبيت Python و Visual Studio Build Tools
انتظر بصبر لمدة 10-15 دقيقة - هذا يثبت أدوات التطوير التي تحتاجها العديد من حزم npm
ستر الكثير من النص يتدحرج - هذا طبيعي! لا تغلق النافذة
اضغط على ENTER عند اكتمال التثبيت للخروج من المثبت

انقر على أي مفتاح مرة أخرى... ربما ستحصل على نافذة منبثقة أخرى تسألك إذا كنت تريد للتطبيق إجراء تغييرات على جهازك، امض قدماً وانقر على نعم للمتابعة مع التثبيت. يجب أن ترى شيئاً مثل هذا:

📦 تثبيت أدوات البناء - قد يستغرق هذا 10-15 دقيقة

انتظر انتهاء التثبيت ثم افعل كما يقول واكتب ENTER في أسفل الطرفية واضغط على زر enter في لوحة المفاتيح للخروج:

إعداد بيئة التطوير

الآن يمكننا الانتقال إلى الجزء الممتع وبدء إحياء تطبيقنا. افتح محرر الكود أولاً. سأستخدم VS Code وما لم تشعر براحة أكبر في استخدام آخر، أنصح باستخدام VS Code، حيث سيكون من الأسهل متابعة هذا البرنامج التعليمي.

افتح الطرفية الخاصة بك. إذا كنت لا تعرف كيف تفعل هذا، انقر على النقاط الثلاث في أعلى محرر الكود وتمرر إلى أسفل إلى 'Terminal'، مرر عليها ثم انقر على 'New Terminal'.

اكتب الأوامر الأربعة التالية في الطرفية، واحداً تلو الآخر:

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: يجري طلبات HTTP إلى APIs أخرى (مثل Spotify)
sentiment: يحلل النص لاكتشاف المشاعر/المزاج
dotenv: يخزن مفاتيح API السرية بأمان
spotify-web-api-node: يتصل بـ Spotify للحصول على بيانات الموسيقى

الآن افتح مجلدك بالذهاب إلى ملف ثم فتح مجلد والبحث عن مجلد يسمى mood-music-api وافتحه.

يجب أن ترى الآن مجلداً يسمى Mood-MUSIC-API في مستكشفك مع node modules وملف package-lock.json وملف package.json بالداخل.

الحصول على مفاتيح 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

أي APIs تخطط لاستخدامها؟

✅ ضع علامة على "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 الخاص بك علناً أبداً!

أضف .env إلى ملف .gitignore الخاص بك باستخدام الأوامر التالية في الطرفية:

# إنشاء ملف .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;

خادم واجهة برمجة التطبيقات لقراءة العقول

أنشئ ملفاً وسمه server.js، أضف الكود التالي واحفظ تغييراتك:

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

// أضف node-fetch لإصدارات Node.js الأقدم
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>واجهة برمجة تطبيقات الموسيقى القارئة للعقول</title>
        <style>
            /* تنسيق تدرج جميل وتحكم صوتي مخصص */
        </style>
    </head>
    <body>
        <div class="container">
            <h1>🧠🎵 واجهة برمجة تطبيقات الموسيقى القارئة للعقول</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(`🚀 واجهة برمجة تطبيقات الموسيقى القارئة للعقول تعمل على http://localhost:${PORT}`);
  console.log('🧠 جاهز لتحليل المزاج وتوليد قوائم التشغيل!');
});

الخطوة 5: اختبار الذكاء الاصطناعي العاطفي

ابدأ خادمك:

node server.js

يجب أن ترى شيئاً مثل هذا:

الآن افتح متصفح الويب الخاص بك واذهب إلى الرابط المحلي الموضح في الصورة أعلاه (http://localhost:3000) لاختبار واجهة برمجة تطبيقات الموسيقى القارئة للعقول!

المخاطر الشائعة التي يجب تجنبها

حدود Spotify API: المستوى المجاني له حدود معدل. قم بتخزين الاستجابات مؤقتاً وتنفيذ منطق إعادة المحاولة للاستخدام الإنتاجي.
سوء تفسير المزاج: اختبر الحالات الحدية مثل السخرية ("رائع، يوم اثنين آخر...") التي قد تربك تحليل المشاعر.
قوائم التشغيل الفارغة: تعامل دائماً مع الحالات التي لا يعيد فيها Spotify توصيات بتوفير أنواع احتياطية.
تعريض مفاتيح API: لا تقم بتسليم ملف .env الخاص بك أبداً. استخدم متغيرات البيئة في الإنتاج.

الخطوات التالية

الآن قمنا ببناء شيء رائع حقاً! إليك كيفية جعله أفضل:

أضف حسابات المستخدمين: احفظ تاريخ المزاج وتفضيلات قوائم التشغيل
التعلم الآلي: درب نماذج مخصصة على تعليقات المستخدمين لتحسين الدقة
الميزات الاجتماعية: دع المستخدمين يشاركون قوائم تشغيل المزاج مع الأصدقاء
تكامل الصوت: اتصل بواجهات برمجة تطبيقات speech-to-text لكشف المزاج الصوتي
تكامل الأجهزة القابلة للارتداء: اقرأ معدل ضربات القلب وبيانات النشاط للحصول على رؤى مزاج أعمق
النشر والتوسع: استخدم Redis للتخزين المؤقت، نفذ مصادقة مناسبة

واجهة برمجة تطبيقات الموسيقى القارئة للعقول يمكنها الآن فهم المشاعر الإنسانية والاستجابة بالموسيقى التصويرية المثالية. هذا الجمع بين تحليل المشاعر بالذكاء الاصطناعي وتنظيم الموسيقى يمثل مستقبل التجارب الشخصية. الإمكانيات لا نهائية!

ترقبوا برنامجنا التعليمي القادم حيث سنطور هذا التطبيق أكثر...