ryan-kazagumo
Version:
A comprehensive Kazagumo plugin providing advanced multi-platform music integration with intelligent URL parsing and cross-service search capabilities. Supports 10 major platforms including Apple Music, Deezer, Spotify, Tidal, Qobuz, JioSaavn, Yandex Musi
279 lines (217 loc) • 7.81 kB
Markdown
# ryan-kazagumo
[](https://www.npmjs.com/package/ryan-kazagumo)
[](https://www.npmjs.com/package/ryan-kazagumo)
[](https://github.com/ryanisnomore/ryan-kazagumo/blob/master/LICENSE)
[](https://github.com/ryanisnomore/ryan-kazagumo/stargazers)
[](https://github.com/ryanisnomore/ryan-kazagumo/network/members)
[](https://github.com/ryanisnomore/ryan-kazagumo/issues)
[](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>