# ryan-kazagumo

[![npm](https://img.shields.io/npm/v/ryan-kazagumo?style=flat-square&logo=npm&color=red)](https://www.npmjs.com/package/ryan-kazagumo)
[![npm](https://img.shields.io/npm/dt/ryan-kazagumo?style=flat-square&logo=npm)](https://www.npmjs.com/package/ryan-kazagumo)
[![GitHub](https://img.shields.io/github/license/ryanisnomore/ryan-kazagumo?style=flat-square&logo=github)](https://github.com/ryanisnomore/ryan-kazagumo/blob/master/LICENSE)
[![GitHub stars](https://img.shields.io/github/stars/ryanisnomore/ryan-kazagumo?style=flat-square&logo=github)](https://github.com/ryanisnomore/ryan-kazagumo/stargazers)
[![GitHub forks](https://img.shields.io/github/forks/ryanisnomore/ryan-kazagumo?style=flat-square&logo=github)](https://github.com/ryanisnomore/ryan-kazagumo/network/members)
[![GitHub issues](https://img.shields.io/github/issues/ryanisnomore/ryan-kazagumo?style=flat-square&logo=github)](https://github.com/ryanisnomore/ryan-kazagumo/issues)
[![Discord](https://img.shields.io/discord/1092123729401745510?label=Support%20Server&style=flat-square&logo=discord)](https://discord.gg/W2GheK3F9m)

A comprehensive multi-platform music plugin for **Kazagumo 3.3.0** with intelligent URL parsing and cross-service search capabilities.

## Supported Platforms

| Platform | Search Engine | Status |
|----------|---------------|--------|
| **Apple Music** | `amsearch` | ✅ |
| **Deezer** | `dzsearch` | ✅ |
| **Spotify** | `spsearch` | ✅ |
| **Tidal** | `tdsearch` | ✅ |
| **Qobuz** | `qbsearch` | ✅ |
| **JioSaavn** | `jssearch` | ✅ |
| **Yandex Music** | `ymsearch` | ✅ |
| **VK Music** | `vksearch` | ✅ |
| **YouTube Music** | `ytmsearch` | ✅ |
| **SoundCloud** | `scsearch` | ✅ |

## Installation

```bash
npm install ryan-kazagumo
```

```bash
yarn add ryan-kazagumo
```

```bash
pnpm add ryan-kazagumo
```

##  Quick Start

```javascript
const { Kazagumo } = require('kazagumo');
const { Connectors } = require('shoukaku');
const { KazagumoMultiPlugin } = require('ryan-kazagumo');

const kazagumo = new Kazagumo({
  plugins: [
    new KazagumoMultiPlugin({
      playlistPageLimit: 1,
      albumPageLimit: 1,
      searchLimit: 10,
      searchMarket: 'US'
    })
  ]
}, new Connectors.DiscordJS(client), nodes);
```

##  Usage Examples

### URL Support
```javascript
// Spotify
kazagumo.search('https://open.spotify.com/track/4iV5W9uYEdYUVa79Axb7Rh');
kazagumo.search('https://spotify.link/zu1pVRAg6Db');

// Apple Music
kazagumo.search('https://music.apple.com/us/album/nevermind/1440783617');

// Deezer
kazagumo.search('https://deezer.com/track/3135556');

// YouTube Music
kazagumo.search('https://music.youtube.com/watch?v=dQw4w9WgXcQ');

// And all other supported platforms...
```

### Search by Engine
```javascript
// Search tracks using specific platforms
kazagumo.search('Rick Astley Never Gonna Give You Up', { engine: 'spotify' });
kazagumo.search('Bohemian Rhapsody', { engine: 'appleMusic' });
kazagumo.search('Hotel California', { engine: 'deezer' });
```

### Advanced Search
```javascript
// Search with custom options
const result = await kazagumo.search('your query', {
  engine: 'spotify',
  requester: interaction.user,
  source: 'spsearch'
});
```

##  Configuration

### Plugin Options

```typescript
interface RyanKazagumoOptions {
  playlistPageLimit?: number;  // Default: 100 tracks per page
  albumPageLimit?: number;     // Default: 50 tracks per page  
  searchLimit?: number;        // Default: 10 (max 50)
  searchMarket?: string;       // Default: 'US'
}
```

### Basic Setup
```javascript
new KazagumoMultiPlugin({
  playlistPageLimit: 1,      // 100 tracks per page
  albumPageLimit: 1,         // 50 tracks per page  
  searchLimit: 10,           // max 50
  searchMarket: 'US'         // country code
})
```

##  Lavalink Setup

### Required Plugins
```yaml
lavalink:
  plugins:
    - dependency: "com.github.topi314.lavasrc:lavasrc-plugin:4.7.0"
      repository: "https://maven.lavalink.dev/releases"
```

### LavaSrc Configuration
```yaml
plugins:
  lavasrc:
    providers:
      - "ytsearch:\"%ISRC%\""
      - "spsearch:\"%ISRC%\""
    spotify:
      clientId: "your_spotify_client_id"
      clientSecret: "your_spotify_client_secret"
      countryCode: "US"
    applemusic:
      countryCode: "US"
```

##  API Reference

### Main Classes

```javascript
// All equivalent - use any one
const { RyanKazagumo } = require('ryan-kazagumo');
const { KazagumoRyan } = require('ryan-kazagumo');
const { KazagumoMultiPlugin } = require('ryan-kazagumo');
```

### Methods

```javascript
// Check platform support
plugin.isPlatformEnabled('spotify');        // true
plugin.isSearchEngineEnabled('amsearch');   // false (returns searchEngine not platform)

// Get available platforms/engines
plugin.getPlatforms();                       // ['appleMusic', 'deezer', ...]
plugin.getSearchEngines();                   // ['appleMusic', 'deezer', ...]
```

## 🎮 Complete Example

```javascript
const { Client, GatewayIntentBits } = require('discord.js');
const { Connectors } = require('shoukaku');
const { Kazagumo } = require('kazagumo');
const { KazagumoMultiPlugin } = require('ryan-kazagumo');

const client = new Client({
  intents: [GatewayIntentBits.Guilds, GatewayIntentBits.GuildVoiceStates]
});

const nodes = [{
  name: 'main',
  url: 'localhost:2333',
  auth: 'youshallnotpass',
  secure: false
}];

const kazagumo = new Kazagumo({
  defaultSearchEngine: 'youtube',
  plugins: [
    new KazagumoMultiPlugin({
      playlistPageLimit: 1,
      albumPageLimit: 1,
      searchLimit: 10,
      searchMarket: 'US'
    })
  ],
  send: (guildId, payload) => {
    const guild = client.guilds.cache.get(guildId);
    if (guild) guild.shard.send(payload);
  }
}, new Connectors.DiscordJS(client), nodes);

client.on('interactionCreate', async (interaction) => {
  if (!interaction.isChatInputCommand() || interaction.commandName !== 'play') return;
  
  const query = interaction.options.getString('query');
  
  try {
    const result = await kazagumo.search(query, {
      requester: interaction.user
    });
    
    if (!result.tracks.length) {
      return interaction.reply('❌ No tracks found!');
    }
    
    const player = await kazagumo.createPlayer({
      guildId: interaction.guild.id,
      voiceId: interaction.member.voice.channel.id,
      textId: interaction.channel.id
    });
    
    player.queue.add(result.tracks[0]);
    if (!player.playing) player.play();
    
    interaction.reply(`🎵 Playing: **${result.tracks[0].title}**`);
    
  } catch (error) {
    interaction.reply('❌ Search failed!');
  }
});

client.login('your_bot_token');
```

##  Links

- **Kazagumo**: [npm](https://www.npmjs.com/package/kazagumo) | [github](https://github.com/Takiyo0/Kazagumo)
- **Shoukaku**: [npm](https://www.npmjs.com/package/shoukaku) | [github](https://github.com/Deivu/Shoukaku)
- **LavaSrc**: [github](https://github.com/topi314/LavaSrc)

##  Version Compatibility

| ryan-kazagumo | Kazagumo | Shoukaku | LavaSrc | Lavalink |
|---------------|----------|----------|---------|----------|
| 1.0.0+ | 3.3.0+ | 4.1.1 | 4.7.2+ | 4.1.1 |

##  License

This project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for details.

##  Contributing

1. Fork the Project
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

##  Support

If this plugin helped you, please consider:
- Starring this repository
- Reporting any bugs
- Suggesting new features
- Sharing with other developers

---

<div align="center">

**Made with ❤️ for the Discord music bot community**

[⬆ Back to Top](#ryan-kazagumo)

</div>