---
## π Teralink: Next-Generation Lavalink Manager
### π§ Modern, Fast, and Extensible Lavalink Client
Teralink is a next-generation, v4-only Lavalink manager for Discord bots, designed for performance, extensibility, and a beautiful developer experience. Enjoy seamless music streaming, advanced queueing, robust event handling, and real-time featuresβall in one open-source package.
---
## π Features
### π₯ New in v0.2.0
- **π§ Smart Search**: Automatic source detection from URLs and query enhancement for better results
- **π‘οΈ Enhanced Error Handling**: Intelligent retry logic with exponential backoff for network errors
- **π Performance Monitoring**: Real-time metrics tracking including cache hit rates and memory usage
- **π§Ή Automatic Memory Management**: Intelligent cleanup and leak prevention with configurable thresholds
- **π Advanced Queue Analytics**: Comprehensive statistics, search functionality, and duplicate detection
- **β‘ Enhanced Caching**: 2.5x larger cache with longer TTL for improved performance
### π΅ Core Features
- Super-performant node management and failover (automatic player migration if a node goes offline)
- Advanced player controls and queueing with real-time analytics
- Multi-source search (YouTube, Spotify, SoundCloud, Apple Music, and more)
- TypeScript support and comprehensive documentation
- Plugin system for extensibility
- Real-time voice channel status sync (statusSync)
- Region-aware node selection and health diagnostics
- Auto-resume, advanced queue, lyrics (including real-time LRC), and more
- **Clean, nested config structure for easier setup**
- **Intelligent caching for super-fast track/playlist resolution**
- **Automatic player migration (failover):** If a Lavalink node goes offline and dynamicSwitching is enabled, Teralink will automatically move all affected players to a healthy node and resume playback from the last position.
---
## π‘ Why Choose Teralink?
- Built for modern Discord bots (Lavalink v4+ only)
- No legacy code, fully open source
- Inspired by the best, but uniquely original
- Designed for both beginners and advanced devs
- Created and maintained by [Ryuzii](https://github.com/Ryuzii)
---
## π¦ Installation
```sh
npm install teralink
```
---
## π Quick Start
```js title="index.js"
const { Teralink } = require('teralink');
const { Client, GatewayIntentBits } = require('discord.js');
const client = new Client({
intents: [
GatewayIntentBits.Guilds,
GatewayIntentBits.GuildMessages,
GatewayIntentBits.GuildVoiceStates,
GatewayIntentBits.MessageContent
]
});
const nodes = [
{ name: 'Lavalink', host: 'localhost', port: 2333, password: 'youshallnotpass', secure: false }
];
function send(packet) {
const guildId = packet.d?.guild_id || packet.guild_id;
if (!guildId) return;
const guild = client.guilds.cache.get(guildId);
if (guild && guild.shard) {
guild.shard.send(packet);
} else if (client.ws && typeof client.ws.send === 'function') {
client.ws.send(packet);
}
}
const tera = new Teralink(client, LAVALINK_NODES, {
send,
source: { default: 'ytmsearch' },
rest: {
version: 'v4',
retryCount: 3,
timeout: 5000
},
plugins: [],
sync: { template: 'Now playing: {title} by {author}' },
resume: {
key: 'teralink-resume',
timeout: 60000
},
node: {
dynamicSwitching: true,
autoReconnect: true,
ws: {
reconnectTries: 5,
reconnectInterval: 5000
}
},
autopauseOnEmpty: true,
lazyLoad: {
enabled: true,
timeout: 5000
}
});
client.once('ready', () => {
tera.init(client.user.id);
console.log(`Logged in as ${client.user.tag}`);
});
// See exampleBot.js for full command and event handling
```
---
## π οΈ Advanced Usage
### π§ Node Management
```js
tera.createNode({ name: 'Backup', host: 'localhost', port: 2444, password: 'backup', secure: false });
tera.destroyNode('Backup');
console.log(tera.getNodesHealth());
console.log(tera.getBestNodeForRegion('us'));
```
### ποΈ Player Controls
```js
player.pause();
player.play();
player.seek(60000); // Seek to 1 minute
player.setVolume(80);
player.filters.setBassboost(true);
player.setLoop('track');
player.queue.shuffle();
```
### π Queue Controls
```js
player.queue.move(0, 3); // Move first track to position 3
player.queue.remove(2); // Remove track at index 2
console.log(player.queue.toArray());
```
### π§ Smart Search (New in v0.2.0)
```js
// Smart search with automatic source detection and query enhancement
const results = await tera.smartSearch('https://open.spotify.com/track/xyz', user);
const enhanced = await tera.smartSearch('lofi hip hop official music video', user, {
limit: 5,
smartSearch: true
});
// Batch search for multiple queries
const queries = ['song1', 'song2', 'song3'];
const batchResults = await tera.batchSearch(queries, user, { limit: 10 });
// Traditional search still available
const yt = await tera.search('ytsearch:lofi hip hop', user);
const sc = await tera.search('scsearch:chill beats', user);
```
### π Performance Monitoring (New in v0.2.0)
```js
// Get comprehensive performance metrics
const metrics = tera.getPerformanceMetrics();
console.log('Cache Hit Rate:', metrics.cacheHitRate + '%');
console.log('Memory Usage:', metrics.memoryUsage.heapUsagePercentage + '%');
// Memory management
const memory = tera.getMemoryUsage();
tera.performMemoryCleanup(); // Manual cleanup
tera.resetPerformanceMetrics();
```
### π Advanced Queue Analytics (New in v0.2.0)
```js
// Comprehensive queue statistics
const stats = player.queue.getStats();
console.log('Total tracks:', stats.totalTracks);
console.log('Estimated playtime:', stats.estimatedPlaytime);
console.log('Unique artists:', stats.uniqueArtists);
// Advanced search within queue
const searchResults = player.queue.searchAdvanced('lofi', {
limit: 5,
fuzzy: true
});
// Queue optimization
const removedCount = player.queue.removeDuplicates('uri');
await player.queue.shuffleAsync();
```
### π’ Events
```js
tera.on('trackStart', (player, track) => { /* ... */ });
tera.on('queueEnd', player => { /* ... */ });
tera.on('playerError', (player, error) => { /* ... */ });
tera.on('debug', message => { console.log(message); });
```
---
## 𧩠Extending Teralink
You can provide your own Player/Queue classes for custom behavior:
```js
class MyPlayer extends Player {
// Custom logic...
}
const tera = new Teralink(client, nodes, {
send,
customPlayerClass: MyPlayer
});
```
---
## π TypeScript Support
- Full types for all classes, options, and events
- Enhanced TypeScript definitions for v0.2.0 features
- See `build/index.d.ts` for details and autocompletion
## π Documentation
- **[Complete Documentation](docs/docs.html)** - Comprehensive guide with examples
- **[API Reference](docs/api.md)** - Detailed API documentation
- **[Examples](docs/examples.md)** - Code examples and use cases
- **[Migration Guide](docs/docs.html#migration)** - Upgrading from v0.1.x to v0.2.0
---
## π€ Example Bot
See [`test/exampleBot.js`](https://github.com/Ryuzii/Teralink/blob/main/test/exampleBot.js) for a real-world Discord.js bot using Teralink, including play, queue, skip, stop, nowplaying, and real-time lyrics commands, and demonstrating the new clean, nested config style.
---
## π€ Contributing
Contributions, issues, and feature requests are welcome!
- Fork the repo and submit a pull request
- Open an issue for bugs or suggestions
---
## π¬ Support
Need help? Join our [Discord server](https://discord.gg/your-invite) or open an issue!
---
## π License
MIT
---
## π Thanks & Acknowledgements
Thank you for choosing **Teralink**!
**Special thanks:**
- The Euralink project and contributors for inspiration
- The Discord music bot community
- Everyone who tests, reports bugs, or contributes ideas
---
β¨ Teralink is proudly created and led by @Ryuzii β¨
All core development, vision, and leadership by @Ryuzii. If you use Teralink, please credit and support the original creator!
---