LavaLink Cache Plugin

A Spring Boot–backed Lavalink plugin that adds a local-first disk cache in front of Lavaplayer's YouTube and Src source managers. When a track is requested, the plugin serves audio straight from disk whenever possible and, on misses, streams from the upstream source while persisting an encoded copy for future playback.

Highlights

• Local-first playback – cached tracks are read from disk through CachedAudioTrack, reducing network usage and startup latency.
• As-you-play caching – TeeAudioTrack streams to the client and asynchronously downloads the original media to a .audio file.
• SQLite-backed index – SqliteCacheIndex tracks metadata, lock state, and LFU metrics for eviction decisions.
• Adaptive eviction – EvictionService enforces disk quotas through a least-frequently-used strategy with aging to avoid stale content.
• Pluggable configuration – Spring Boot auto-configuration wires everything through the plugins.cache namespace.

Project layout

.
├── build.gradle.kts        # Kotlin + dependency management
├── settings.gradle.kts
└── src/main/kotlin/
    └── com/lavalink/cache/
        ├── config/         # CacheConfig + Spring properties binding
        ├── eviction/       # EvictionService and policies
        ├── index/          # CacheIndex interface + SQLite implementation
        ├── key/            # Cache key normalization utilities
        ├── spring/         # Auto-configuration entry point
        └── track/          # Cached/Tee tracks and source manager

Getting started

Prerequisites

• JDK 17+
• Gradle 8+ (install locally or generate a wrapper via gradle wrapper once)
• A Lavalink server that supports plugins (plugin API 4.x)

Build

Run the test suite and assemble the plugin JAR:

# from the repository root
gradle clean build

If you prefer to ship a wrapper into the repo:

gradle wrapper --gradle-version 8.10
./gradlew.bat clean build

The compiled artifact will appear under build/libs/.

Install into Lavalink

1. Copy the built JAR into Lavalink's plugins/ directory.
2. Add configuration to application.yml (see below).
3. Restart Lavalink.

Configuration

Configure the plugin with the plugins.cache namespace. Default values live in CacheProperties.

plugins:
  cache:
    enabled: true               # Toggle the cache source manager
    directory: data/cache       # Where cached audio files are stored
    db-file: data/cache/cache.db
    max-bytes: 50_000_000       # Disk quota before eviction kicks in
    min-keep-bytes: 524288      # Discard partial downloads below this size
    lock-timeout: 600s          # How long to wait before forcing unlock
    eviction-interval: 60s      # Background eviction cadence

Restart Lavalink after adjusting configuration.

How it works

1. Lookup – CachedSourceManager normalizes the identifier into a CacheKey and tries SqliteCacheIndex for a ready entry.
2. Hit – CachedAudioTrack streams directly from the cached .audio file.
3. Miss – TeeAudioTrack delegates playback to the original source while BackgroundDownloader persists the upstream bytes. When the download completes, the index marks the entry as ready for reuse.
4. Eviction – EvictionService watches size/age metrics and prunes least-used items while respecting active locks.

Development tips

• The plugin relies on Spring auto-configuration (CacheAutoConfiguration) registered via META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports.
• Cache metadata lives in SQLite; inspect it with any standard SQLite client when debugging.
• Logging is provided by Logback; adjust levels via Lavalink's logging configuration if you need more insight.

Roadmap

• REST endpoints for cache introspection and manual invalidation.
• Smarter header propagation to support authenticated sources.
• Metrics export (Micrometer/Prometheus) for cache hit ratios.

Contributions and issue reports are very welcome—feel free to open a ticket or submit a PR with enhancements!