Custom Filters
Learn how to create and manage custom audio filters in Yukino.
Filter Utilities
Yukino provides a comprehensive FilterUtil class to help with filter creation and manipulation:
import { FilterUtil } from 'yukinojs';
// Create a flat equalizer (all bands set to 0.0)
const flatEQ = FilterUtil.createFlatEQ();
// Create a bass boost equalizer
const bassBoostEQ = FilterUtil.createBassBoostEQ(0.6); // 0.6 gain
// Use built-in presets
const nightcoreFilter = FilterUtil.nightcorePreset();
const vaporwaveFilter = FilterUtil.vaporwavePreset();
const eightDFilter = FilterUtil.eightDimensionalPreset();
const nightModeFilter = FilterUtil.nightModePreset();
const enhancedVocalsFilter = FilterUtil.enhancedVocalsPreset();
Custom Filter Manager
The CustomFilterManager class allows you to create and manage custom filter combinations:
import { CustomFilterManager } from 'yukinojs';
const filterManager = new CustomFilterManager();
// Add filters with optional description and tags
filterManager.addFilter('night-mode', FilterUtil.nightModePreset(),
'Reduces treble and enhances bass for nighttime listening',
['night', 'bass', 'comfort']);
filterManager.addFilter('enhanced-vocals', FilterUtil.enhancedVocalsPreset(),
'Enhances the vocal frequencies',
['vocals', 'clarity']);
// Apply a filter to a player
await filterManager.applyFilter(player, 'night-mode');
// Get a specific filter
const filter = filterManager.getFilter('night-mode');
// Get all filter names
const filterNames = filterManager.getFilterNames();
// Get all filters
const allFilters = filterManager.getAllFilters();
// Find filters by tag
const nightFilters = filterManager.findFiltersByTag('night');
// Update an existing filter
filterManager.updateFilter('night-mode', {
...FilterUtil.nightModePreset(),
volume: 80
});
// Remove a filter
filterManager.removeFilter('night-mode');
// Clear all filters
filterManager.clearFilters();
Event Handling
The CustomFilterManager supports events to help you respond to filter changes:
filterManager.on('filterAdded', (data) => {
console.log(`New filter added: ${data.name}`);
});
filterManager.on('filterRemoved', (data) => {
console.log(`Filter removed: ${data.name}`);
});
filterManager.on('filterUpdated', (data) => {
console.log(`Filter updated: ${data.name}`);
});
filterManager.on('filterApplied', (data) => {
console.log(`Applied filter ${data.name} to player in guild ${data.player.guildId}`);
});
filterManager.on('filterInterpolationComplete', (data) => {
console.log(`Filter interpolation complete for player in guild ${data.player.guildId}`);
});
// Remove event listener
filterManager.off('filterAdded', myCallback);
Filter Interpolation
Create smooth transitions between filters:
// Using the CustomFilterManager
await filterManager.interpolateFilters(
player,
FilterUtil.nightModePreset(),
{ steps: 15, duration: 1000 }
);
// Using FilterUtil directly
const currentFilters = player.filters;
const targetFilters = FilterUtil.enhancedVocalsPreset();
for (let i = 1; i <= 10; i++) {
const fraction = i / 10;
const interpolated = FilterUtil.interpolateFilterValues(
currentFilters,
targetFilters,
fraction
);
await player.setFilters(interpolated);
await new Promise(r => setTimeout(r, 50));
}
Dynamic Filter Generation
Create filters based on parameters:
const dynamicFilter = FilterUtil.createDynamicFilter({
bassBoost: 0.5, // 0-1 range
trebleBoost: 0.3, // 0-1 range
vibrato: 0.2, // 0-1 range
tempo: 1.2 // Playback speed
});
await player.setFilters(dynamicFilter);
Filter Chain System
Chain multiple filters together:
import { FilterChain } from 'yukinojs';
const chain = new FilterChain('my-chain');
// Add filters to the chain
chain.add(FilterUtil.nightModePreset())
.add({ volume: 80 })
.add({ timescale: { pitch: 1.1 } });
// Add a named filter from the filter manager
chain.addNamed(filterManager, 'enhanced-vocals');
// Apply the chain to a player
await chain.apply(player);
// Get the combined filter
const combinedFilter = chain.combine();
// Reset the chain
chain.reset();
// Get/set chain name
const name = chain.getName();
chain.setName('new-chain');
Cached Filter Manager
Optimize performance by caching generated filters:
import { CachedFilterManager } from 'yukinojs';
// Create with a TTL of 1 hour (default)
const cachedFilters = new CachedFilterManager(3600000);
// Get a filter (generates if not in cache)
const filter = cachedFilters.getFilter('dynamic-bass-0.5', () =>
FilterUtil.createDynamicFilter({ bassBoost: 0.5 })
);
// Explicitly add a filter to cache
cachedFilters.cacheFilter('my-special-filter', {
equalizer: FilterUtil.createBassBoostEQ(0.7)
});
// Remove a filter from cache
cachedFilters.invalidate('dynamic-bass-0.5');
// Clear the entire cache
cachedFilters.clear();
// Adjust TTL
cachedFilters.setTTL(7200000); // 2 hours
Utility Functions
Yukino provides additional utility functions:
// Validate filters
FilterUtil.validateFilters({
volume: 80,
equalizer: [{ band: 0, gain: 0.5 }]
});
// Linear interpolation
const interpolated = FilterUtil.lerp(0, 100, 0.5); // 50
// Combine multiple filters
const combined = FilterUtil.combineFilters(
FilterUtil.nightModePreset(),
{ volume: 80 },
{ timescale: { speed: 1.2 } }
);
Best Practices
-
Validate filters before applying them:
try {
FilterUtil.validateFilters(myCustomFilter);
await player.setFilters(myCustomFilter);
} catch (error) {
console.error('Invalid filter settings:', error.message);
} -
Use filter interpolation for smooth transitions:
// Instead of abrupt changes:
await player.setFilters(targetFilters);
// Use interpolation:
await filterManager.interpolateFilters(player, targetFilters, {
steps: 12,
duration: 600
}); -
Cache complex filter combinations:
// For frequently used dynamic filters
const cachedManager = new CachedFilterManager();
function getComplexFilter(params) {
const key = `complex-${params.bass}-${params.treble}`;
return cachedManager.getFilter(key, () => {
// Complex calculation here
return { /* filter */ };
});
} -
Group related filters with tags:
filterManager.addFilter('bass-boost-low',
FilterUtil.createBassBoostEQ(0.3),
'Low bass boost',
['bass', 'low-intensity']
);
filterManager.addFilter('bass-boost-high',
FilterUtil.createBassBoostEQ(0.7),
'High bass boost',
['bass', 'high-intensity']
);
// Later, find all bass filters
const bassFilters = filterManager.findFiltersByTag('bass'); -
Throttle filter updates for performance:
// CustomFilterManager already implements this internally
// for interpolation, but for custom code:
let lastUpdate = 0;
const UPDATE_INTERVAL = 50; // ms
async function updateFilters(player, filters) {
const now = Date.now();
if (now - lastUpdate < UPDATE_INTERVAL) return;
lastUpdate = now;
await player.setFilters(filters);
}