🎵 RcSpotLR

Simple and powerful lyrics finder library with synced lyrics support

Installation • Quick Start • Documentation • Bot Integration

✨ Features

• 🔍 Easy Search - Find lyrics by track name and artist
• ⏱️ Synced Lyrics - Get timestamped lyrics in LRC format
• 📝 Plain Lyrics - Get plain text lyrics without timestamps
• 🚀 Simple API - Clean and intuitive methods
• ⚡ Fast - Optimized performance with axios
• 🛡️ Error Handling - Comprehensive error messages
• 🔑 No API Key Required - Ready to use out of the box
• 🤖 Bot Ready - Perfect for Telegram & WhatsApp bots

📦 Installation

npm install rcspotlr

or with yarn:

yarn add rcspotlr

🚀 Quick Start

const RcSpotLR = require('rcspotlr');

const client = new RcSpotLR();

async function findLyrics() {
  const lyrics = await client.getLyrics('Shape of You', 'Ed Sheeran');
  console.log(lyrics);
}

findLyrics();

📚 Documentation

Initialization

const RcSpotLR = require('rcspotlr');

const client = new RcSpotLR(baseURL);

Parameters:

• baseURL (string, optional) - Custom API base URL (default: https://your-api.vercel.app)

Example:

const client = new RcSpotLR();

const customClient = new RcSpotLR('https://custom-api.com');

Methods

search(query)

Search for lyrics using a raw query string.

Parameters:

• query (string) - Search query (e.g., "Bohemian Rhapsody" or "Bohemian Rhapsody - Queen")

Returns: Promise<Object> - Full API response

Example:

const results = await client.search('Wonderwall - Oasis');
console.log(results);

Response:

{
  "success": true,
  "query": "Wonderwall - Oasis",
  "results": [
    {
      "id": 123,
      "trackName": "Wonderwall",
      "artistName": "Oasis",
      "albumName": "(What's the Story) Morning Glory?",
      "duration": 258,
      "plainLyrics": "Today is gonna be the day...",
      "syncedLyrics": "[00:00.00]Today is gonna be the day..."
    }
  ],
  "creator": "RiiCODE"
}

searchByTrack(trackName, artistName)

Search for lyrics by track name and optional artist name.

Parameters:

• trackName (string) - Name of the track
• artistName (string, optional) - Name of the artist

Returns: Promise<Object> - Full API response

Example:

const results = await client.searchByTrack('Perfect', 'Ed Sheeran');

const results2 = await client.searchByTrack('Perfect');

getLyrics(trackName, artistName)

Get the first matching lyrics result.

Parameters:

• trackName (string) - Name of the track
• artistName (string, optional) - Name of the artist

Returns: Promise<Object|null> - Lyrics object or null if not found

Example:

const lyrics = await client.getLyrics('Blinding Lights', 'The Weeknd');

if (lyrics) {
  console.log(`Track: ${lyrics.trackName}`);
  console.log(`Artist: ${lyrics.artistName}`);
  console.log(`Duration: ${lyrics.duration}s`);
  console.log(`Plain Lyrics: ${lyrics.plainLyrics}`);
  console.log(`Synced Lyrics: ${lyrics.syncedLyrics}`);
} else {
  console.log('Lyrics not found');
}

getSyncedLyrics(trackName, artistName)

Get only the synced lyrics (LRC format) for a track.

Parameters:

• trackName (string) - Name of the track
• artistName (string, optional) - Name of the artist

Returns: Promise<string|null> - Synced lyrics or null if not found

Example:

const syncedLyrics = await client.getSyncedLyrics('Levitating', 'Dua Lipa');

if (syncedLyrics) {
  console.log(syncedLyrics);
} else {
  console.log('Synced lyrics not available');
}

getPlainLyrics(trackName, artistName)

Get only the plain text lyrics for a track.

Parameters:

• trackName (string) - Name of the track
• artistName (string, optional) - Name of the artist

Returns: Promise<string|null> - Plain lyrics or null if not found

Example:

const plainLyrics = await client.getPlainLyrics('Circles', 'Post Malone');

if (plainLyrics) {
  console.log(plainLyrics);
} else {
  console.log('Lyrics not found');
}

health()

Check if the API service is running.

Returns: Promise<Object> - Health status

Example:

const status = await client.health();
console.log(status);

🤖 Bot Integration

Telegram Bot Integration

Using Telegraf

const { Telegraf } = require('telegraf');
const RcSpotLR = require('rcspotlr');

const bot = new Telegraf('YOUR_BOT_TOKEN');
const lyricsClient = new RcSpotLR();

bot.command('lyrics', async (ctx) => {
  const query = ctx.message.text.replace('/lyrics', '').trim();
  
  if (!query) {
    return ctx.reply('Usage: /lyrics <track name> - <artist>\nExample: /lyrics Perfect - Ed Sheeran');
  }
  
  try {
    await ctx.reply('🔍 Searching for lyrics...');
    
    const lyrics = await lyricsClient.getLyrics(query);
    
    if (!lyrics) {
      return ctx.reply('❌ Lyrics not found. Try adding the artist name:\n/lyrics <track> - <artist>');
    }
    
    const message = `
🎵 *${lyrics.trackName}*
🎤 Artist: ${lyrics.artistName}
📀 Album: ${lyrics.albumName || 'Unknown'}
⏱️ Duration: ${Math.floor(lyrics.duration / 60)}:${(lyrics.duration % 60).toString().padStart(2, '0')}

📝 *Lyrics:*
${lyrics.plainLyrics || 'Plain lyrics not available'}

_Powered by RcSpotLR_
    `.trim();
    
    await ctx.reply(message, { parse_mode: 'Markdown' });
    
    if (lyrics.syncedLyrics) {
      await ctx.reply('💡 Synced lyrics (LRC) are available! Use /synced to get them.');
    }
    
  } catch (error) {
    console.error('Error:', error);
    ctx.reply('❌ An error occurred while fetching lyrics. Please try again later.');
  }
});

bot.command('synced', async (ctx) => {
  const query = ctx.message.text.replace('/synced', '').trim();
  
  if (!query) {
    return ctx.reply('Usage: /synced <track name> - <artist>\nExample: /synced Perfect - Ed Sheeran');
  }
  
  try {
    await ctx.reply('🔍 Fetching synced lyrics...');
    
    const syncedLyrics = await lyricsClient.getSyncedLyrics(query);
    
    if (!syncedLyrics) {
      return ctx.reply('❌ Synced lyrics not available for this track.');
    }
    
    const message = `🎤 *Synced Lyrics (LRC Format)*\n\n\`\`\`\n${syncedLyrics}\n\`\`\`\n\n_Powered by RcSpotLR_`;
    
    await ctx.reply(message, { parse_mode: 'Markdown' });
    
  } catch (error) {
    console.error('Error:', error);
    ctx.reply('❌ An error occurred. Please try again.');
  }
});

bot.command('start', (ctx) => {
  ctx.reply(`
👋 Welcome to Lyrics Bot!

Available commands:
/lyrics <track> - <artist> - Get song lyrics
/synced <track> - <artist> - Get synced lyrics (LRC)
/help - Show help message

Example:
/lyrics Perfect - Ed Sheeran

Powered by RcSpotLR 🎵
  `);
});

bot.command('help', (ctx) => {
  ctx.reply(`
📚 *Help Menu*

*Commands:*
/lyrics <track> - Get song lyrics
/synced <track> - Get synced lyrics
/help - Show this help

*Usage Examples:*
/lyrics Shape of You - Ed Sheeran
/lyrics Perfect
/synced Blinding Lights - The Weeknd

*Tips:*
• Include artist name for better results
• Synced lyrics include timestamps
• Use /synced for karaoke-style lyrics

_Powered by RcSpotLR by RiiCODE_
  `, { parse_mode: 'Markdown' });
});

bot.launch();

console.log('✅ Telegram bot is running...');

process.once('SIGINT', () => bot.stop('SIGINT'));
process.once('SIGTERM', () => bot.stop('SIGTERM'));

Using node-telegram-bot-api

const TelegramBot = require('node-telegram-bot-api');
const RcSpotLR = require('rcspotlr');

const token = 'YOUR_BOT_TOKEN';
const bot = new TelegramBot(token, { polling: true });
const lyricsClient = new RcSpotLR();

bot.onText(/\/lyrics (.+)/, async (msg, match) => {
  const chatId = msg.chat.id;
  const query = match[1];
  
  try {
    await bot.sendMessage(chatId, '🔍 Searching for lyrics...');
    
    const lyrics = await lyricsClient.getLyrics(query);
    
    if (!lyrics) {
      return bot.sendMessage(chatId, '❌ Lyrics not found. Try: /lyrics <track> - <artist>');
    }
    
    const message = `
🎵 *${lyrics.trackName}*
🎤 Artist: ${lyrics.artistName}
📀 Album: ${lyrics.albumName || 'Unknown'}
⏱️ Duration: ${Math.floor(lyrics.duration / 60)}:${(lyrics.duration % 60).toString().padStart(2, '0')}

📝 *Lyrics:*
${lyrics.plainLyrics || 'Plain lyrics not available'}

_Powered by RcSpotLR_
    `.trim();
    
    await bot.sendMessage(chatId, message, { parse_mode: 'Markdown' });
    
  } catch (error) {
    console.error('Error:', error);
    bot.sendMessage(chatId, '❌ Error fetching lyrics. Please try again.');
  }
});

bot.onText(/\/synced (.+)/, async (msg, match) => {
  const chatId = msg.chat.id;
  const query = match[1];
  
  try {
    await bot.sendMessage(chatId, '🔍 Fetching synced lyrics...');
    
    const syncedLyrics = await lyricsClient.getSyncedLyrics(query);
    
    if (!syncedLyrics) {
      return bot.sendMessage(chatId, '❌ Synced lyrics not available.');
    }
    
    const message = `🎤 *Synced Lyrics (LRC)*\n\n\`\`\`\n${syncedLyrics}\n\`\`\`\n\n_Powered by RcSpotLR_`;
    
    await bot.sendMessage(chatId, message, { parse_mode: 'Markdown' });
    
  } catch (error) {
    console.error('Error:', error);
    bot.sendMessage(chatId, '❌ Error fetching synced lyrics.');
  }
});

bot.onText(/\/start/, (msg) => {
  const chatId = msg.chat.id;
  bot.sendMessage(chatId, `
👋 Welcome to Lyrics Bot!

Commands:
/lyrics <track> - <artist> - Get lyrics
/synced <track> - <artist> - Get synced lyrics

Example: /lyrics Perfect - Ed Sheeran

Powered by RcSpotLR 🎵
  `);
});

console.log('✅ Telegram bot is running...');

WhatsApp Bot Integration

Using @whiskeysockets/baileys

const { default: makeWASocket, DisconnectReason, useMultiFileAuthState } = require('@whiskeysockets/baileys');
const RcSpotLR = require('rcspotlr');

const lyricsClient = new RcSpotLR();

async function connectToWhatsApp() {
  const { state, saveCreds } = await useMultiFileAuthState('auth_info_baileys');
  
  const sock = makeWASocket({
    auth: state,
    printQRInTerminal: true
  });
  
  sock.ev.on('creds.update', saveCreds);
  
  sock.ev.on('connection.update', (update) => {
    const { connection, lastDisconnect } = update;
    if (connection === 'close') {
      const shouldReconnect = lastDisconnect?.error?.output?.statusCode !== DisconnectReason.loggedOut;
      console.log('Connection closed. Reconnecting:', shouldReconnect);
      if (shouldReconnect) {
        connectToWhatsApp();
      }
    } else if (connection === 'open') {
      console.log('✅ WhatsApp bot connected!');
    }
  });
  
  sock.ev.on('messages.upsert', async ({ messages }) => {
    const msg = messages[0];
    if (!msg.message || msg.key.fromMe) return;
    
    const text = msg.message.conversation || msg.message.extendedTextMessage?.text || '';
    const from = msg.key.remoteJid;
    
    if (text.startsWith('.lyrics')) {
      const query = text.replace('.lyrics', '').trim();
      
      if (!query) {
        await sock.sendMessage(from, {
          text: '📚 *Lyrics Bot*\n\nUsage: .lyrics <track> - <artist>\n\nExample:\n.lyrics Perfect - Ed Sheeran\n\n_Powered by RcSpotLR_'
        });
        return;
      }
      
      try {
        await sock.sendMessage(from, { text: '🔍 Searching for lyrics...' });
        
        const lyrics = await lyricsClient.getLyrics(query);
        
        if (!lyrics) {
          await sock.sendMessage(from, {
            text: '❌ Lyrics not found. Try adding artist name:\n.lyrics <track> - <artist>'
          });
          return;
        }
        
        const response = `
🎵 *${lyrics.trackName}*
🎤 Artist: ${lyrics.artistName}
📀 Album: ${lyrics.albumName || 'Unknown'}
⏱️ Duration: ${Math.floor(lyrics.duration / 60)}:${(lyrics.duration % 60).toString().padStart(2, '0')}

━━━━━━━━━━━━━━━━━

📝 *Lyrics:*

${lyrics.plainLyrics || 'Plain lyrics not available'}

━━━━━━━━━━━━━━━━━
_Powered by RcSpotLR by RiiCODE_
        `.trim();
        
        await sock.sendMessage(from, { text: response });
        
        if (lyrics.syncedLyrics) {
          await sock.sendMessage(from, {
            text: '💡 Tip: Use .synced to get synced lyrics (LRC format)'
          });
        }
        
      } catch (error) {
        console.error('Error:', error);
        await sock.sendMessage(from, {
          text: '❌ An error occurred. Please try again later.'
        });
      }
    }
    
    if (text.startsWith('.synced')) {
      const query = text.replace('.synced', '').trim();
      
      if (!query) {
        await sock.sendMessage(from, {
          text: 'Usage: .synced <track> - <artist>\n\nExample: .synced Perfect - Ed Sheeran'
        });
        return;
      }
      
      try {
        await sock.sendMessage(from, { text: '🔍 Fetching synced lyrics...' });
        
        const syncedLyrics = await lyricsClient.getSyncedLyrics(query);
        
        if (!syncedLyrics) {
          await sock.sendMessage(from, {
            text: '❌ Synced lyrics not available for this track.'
          });
          return;
        }
        
        const response = `
🎤 *Synced Lyrics (LRC Format)*

${syncedLyrics}

_Powered by RcSpotLR by RiiCODE_
        `.trim();
        
        await sock.sendMessage(from, { text: response });
        
      } catch (error) {
        console.error('Error:', error);
        await sock.sendMessage(from, {
          text: '❌ Error fetching synced lyrics.'
        });
      }
    }
    
    if (text === '.help' || text === '.menu') {
      const helpMessage = `
┏━━━━━━━━━━━━━━━━━━┓
┃  🎵 *LYRICS BOT*  ┃
┗━━━━━━━━━━━━━━━━━━┛

*Commands:*
• .lyrics <track> - <artist>
  Get song lyrics

• .synced <track> - <artist>
  Get synced lyrics (LRC)

• .help
  Show this menu

*Examples:*
.lyrics Perfect - Ed Sheeran
.lyrics Shape of You
.synced Blinding Lights - The Weeknd

*Tips:*
✓ Include artist for better results
✓ Synced lyrics include timestamps
✓ Perfect for karaoke!

━━━━━━━━━━━━━━━━━━
_Powered by RcSpotLR by RiiCODE 2025_
      `.trim();
      
      await sock.sendMessage(from, { text: helpMessage });
    }
  });
  
  return sock;
}

connectToWhatsApp();

Advanced WhatsApp Bot Example

const { default: makeWASocket, DisconnectReason, useMultiFileAuthState } = require('@whiskeysockets/baileys');
const RcSpotLR = require('rcspotlr');
const fs = require('fs');

const lyricsClient = new RcSpotLR();

async function startBot() {
  const { state, saveCreds } = await useMultiFileAuthState('auth_info');
  
  const sock = makeWASocket({
    auth: state,
    printQRInTerminal: true
  });
  
  sock.ev.on('creds.update', saveCreds);
  
  sock.ev.on('connection.update', async (update) => {
    const { connection, lastDisconnect } = update;
    
    if (connection === 'close') {
      const shouldReconnect = lastDisconnect?.error?.output?.statusCode !== DisconnectReason.loggedOut;
      if (shouldReconnect) {
        startBot();
      }
    } else if (connection === 'open') {
      console.log('✅ Bot connected successfully!');
    }
  });
  
  sock.ev.on('messages.upsert', async ({ messages, type }) => {
    if (type !== 'notify') return;
    
    const msg = messages[0];
    if (!msg.message || msg.key.fromMe) return;
    
    const messageType = Object.keys(msg.message)[0];
    const messageContent = msg.message[messageType];
    const text = messageContent?.text || messageContent?.caption || messageContent || '';
    const from = msg.key.remoteJid;
    
    const command = text.toLowerCase().split(' ')[0];
    const args = text.slice(command.length).trim();
    
    const reply = async (text) => {
      await sock.sendMessage(from, { text }, { quoted: msg });
    };
    
    switch (command) {
      case '.lyrics':
      case '.lirik':
        if (!args) {
          await reply('📝 Usage: .lyrics <song> - <artist>\n\nExample: .lyrics Perfect - Ed Sheeran');
          return;
        }
        
        try {
          await reply('🔍 Searching...');
          
          const lyrics = await lyricsClient.getLyrics(args);
          
          if (!lyrics) {
            await reply('❌ Lyrics not found!');
            return;
          }
          
          let response = `╭─「 🎵 LYRICS 」\n`;
          response += `│ Title: ${lyrics.trackName}\n`;
          response += `│ Artist: ${lyrics.artistName}\n`;
          response += `│ Album: ${lyrics.albumName || '-'}\n`;
          response += `│ Duration: ${Math.floor(lyrics.duration / 60)}:${(lyrics.duration % 60).toString().padStart(2, '0')}\n`;
          response += `╰────────────────\n\n`;
          response += `${lyrics.plainLyrics}\n\n`;
          response += `_Powered by RcSpotLR_`;
          
          await reply(response);
          
        } catch (error) {
          await reply('❌ Error: ' + error.message);
        }
        break;
        
      case '.synced':
      case '.lrc':
        if (!args) {
          await reply('📝 Usage: .synced <song> - <artist>\n\nExample: .synced Perfect - Ed Sheeran');
          return;
        }
        
        try {
          await reply('🔍 Fetching synced lyrics...');
          
          const syncedLyrics = await lyricsClient.getSyncedLyrics(args);
          
          if (!syncedLyrics) {
            await reply('❌ Synced lyrics not available!');
            return;
          }
          
          await reply(`🎤 Synced Lyrics:\n\n${syncedLyrics}\n\n_Powered by RcSpotLR_`);
          
        } catch (error) {
          await reply('❌ Error: ' + error.message);
        }
        break;
        
      case '.menu':
      case '.help':
        const menu = `
╭─「 🎵 LYRICS BOT 」
│
│ ⚡ *Commands:*
│ • .lyrics <song> - <artist>
│   Get song lyrics
│
│ • .synced <song> - <artist>
│   Get synced lyrics (LRC)
│
│ • .menu
│   Show this menu
│
│ 📝 *Examples:*
│ .lyrics Perfect - Ed Sheeran
│ .synced Blinding Lights
│
╰────────────────

_Powered by RcSpotLR by RiiCODE 2025_
        `.trim();
        
        await reply(menu);
        break;
    }
  });
}

startBot();

💡 More Examples

Music Player Integration

const RcSpotLR = require('rcspotlr');

class MusicPlayer {
  constructor() {
    this.lyricsClient = new RcSpotLR();
    this.currentTrack = null;
    this.currentLyrics = null;
  }

  async loadTrack(trackName, artistName) {
    console.log(`Loading: ${trackName} by ${artistName}...`);
    
    this.currentTrack = { trackName, artistName };
    this.currentLyrics = await this.lyricsClient.getSyncedLyrics(trackName, artistName);
    
    if (this.currentLyrics) {
      console.log('✅ Synced lyrics loaded!');
      return true;
    } else {
      console.log('⚠️ No synced lyrics available');
      return false;
    }
  }

  displayLyrics() {
    if (!this.currentLyrics) {
      console.log('No lyrics loaded');
      return;
    }

    console.log('\n🎤 Synced Lyrics:\n');
    console.log(this.currentLyrics);
  }
}

const player = new MusicPlayer();

async function run() {
  await player.loadTrack('Perfect', 'Ed Sheeran');
  player.displayLyrics();
}

run();

Batch Lyrics Fetcher

const RcSpotLR = require('rcspotlr');

const client = new RcSpotLR();

const playlist = [
  { track: 'Shape of You', artist: 'Ed Sheeran' },
  { track: 'Blinding Lights', artist: 'The Weeknd' },
  { track: 'Levitating', artist: 'Dua Lipa' }
];

async function fetchPlaylistLyrics() {
  console.log('🎵 Fetching lyrics for playlist...\n');
  
  for (const song of playlist) {
    try {
      const lyrics = await client.getLyrics(song.track, song.artist);
      
      if (lyrics) {
        console.log(`✅ ${song.track} - ${song.artist}`);
        console.log(`   Duration: ${lyrics.duration}s`);
        console.log(`   Has synced lyrics: ${lyrics.syncedLyrics ? 'Yes' : 'No'}\n`);
      } else {
        console.log(`❌ ${song.track} - ${song.artist} (not found)\n`);
      }
    } catch (error) {
      console.log(`❌ ${song.track} - ${song.artist} (error)\n`);
    }
  }
}

fetchPlaylistLyrics();

🔧 Error Handling

const RcSpotLR = require('rcspotlr');

const client = new RcSpotLR();

async function safeSearch(trackName, artistName) {
  try {
    const lyrics = await client.getLyrics(trackName, artistName);
    return lyrics;
  } catch (error) {
    if (error.message.includes('Network')) {
      console.error('❌ Network error - check your connection');
    } else {
      console.error('❌ Error:', error.message);
    }
    return null;
  }
}

safeSearch('Perfect', 'Ed Sheeran');

🛠️ Requirements

• Node.js >= 14.0.0
• npm or yarn

📝 License

MIT License - see LICENSE file for details

🤝 Contributing

Contributions are welcome!

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

🐛 Bug Reports

If you find a bug, please open an issue on GitHub with:

• Description of the bug
• Steps to reproduce
• Expected behavior
• Actual behavior

📧 Support

For questions or support:

• Open an issue on GitHub
• Contact via email (if provided)

🙏 Credits

This package uses the LRCLIB API for lyrics data.

Made with ❤️ by RiiCODE

© 2025 RiiCODE. All rights reserved.

⬆ Back to Top