SolaceAudio

High-Throughput Audio Ingestion & Playback Engine for Lavalink v4

A distributed, resilient audio routing layer for high-concurrency voice nodes. Integrates deterministic candidate scoring, single-flight search deduplication, dynamic client signature rotation, and multi-platform metadata synchronization.

Architecture • Source Matrix • Quick Start • Bypass Engine • Amazon Music API • Scoring Pipeline • Credits

---

System Architecture

SolaceAudio is engineered from the ground up to solve upstream rate-limiting, IP pool degradation, and track mismatch anomalies in production Discord environments:

Subsystem	Technical Specification	Operational Impact
Single-Flight Coalescing	Concurrent duplicate query deduplication with lock-free atomic futures	Eliminates upstream burst spikes during automated queue ingestion
oEmbed Resolution & Multilingual Normalization	Lightweight JSON oEmbed fallback coupled with Unicode script & Indic matra preservation	Guarantees 100% accurate metadata extraction for direct URLs even when datacenter IPs are blocked
Deterministic Scoring	Levenshtein distance matching, delta duration checks (±2s window), and noise token filtering	Prevents covers, pitch-shifted edits, and noisy music video rips during audio mirroring
Dynamic Client Rotation	Automated round-robin client handshakes (Android VR Quest 2, VisionOS, Web Remix)	Bypasses upstream signature throttling and eliminates HTTP 403 / 429 backpressure
Atomic Disk Caching	Direct zero-copy streaming coupled with transactional .part buffer swaps	Instant subsequent playback with zero memory leak risk and zero database dependencies
Cascade Failover	Automated provider sequence failover (Deezer → YouTube → SoundCloud → Bandcamp)	Guarantees uninterrupted audio streaming if any single upstream provider goes down

---

Source Matrix

Provider	Ingestion Mode	Stream Output	Authentication Pipeline	Status
Spotify	ISRC & Metadata Mirror	320kbps / 160kbps MP3/Opus	Nuance Metadata Schema
Apple Music	amsearch:, Albums, Playlists	High-Fidelity Audio Mirror	Auto-scraped Developer Bearer Token
YouTube	VisionOS / Cobalt TV / TvCast / Web	160kbps Opus / AAC	Zero-BotGuard TV Downgrade & PoToken
Deezer	Direct Blowfish Decryption	Direct 320kbps MP3 / FLAC	In-Process Blowfish-CBC & Optional ARL
JioSaavn	Native Audio Extraction	Up to 320kbps MP4 Container	Public CDN Edge
Gaana	Native Chunked Stream	Master CDN HLS Transport	Public Stream Endpoint
Amazon Music	Metadata Cross-Resolution	High-Fidelity Mirror	Public Search Pipeline
Pandora	Direct Stream Resolution	Adaptive Bitrate AAC	None Required
FloweryTTS	Real-time Neural Synthesis	Uncompressed PCM Audio	Public API Pipeline
Last.fm	Contextual Recommendation Graph	Algorithmic Metadata	Optional API Key
Synced Lyrics	LRCLIB / Deezer / Genius / Spotify	Time-stamped LRC & Text	Zero-Auth Auto Fallback Engine
SponsorBlock	Non-Music Segment Elimination	Gapless Audio Playback	Official SponsorBlock API & Cache

---

Quick Start

1. Lavalink Node Installation

Add the plugin dependency to your application.yml:

lavalink:
  plugins:
    - dependency: "com.github.Nex-Devz.SolaceAudio:solaceaudio-plugin:1.0.22"
      repository: "https://jitpack.io"

2. Comprehensive Configuration

plugins:
  solaceaudio:
    sources:
      spotify: true
      jiosaavn: true
      gaana: true
      deezer: true
      youtube: true
      amazonmusic: true
      pandora: true
      flowerytts: true

    # Priority mirror ladder
    providers:
      - "dzisrc:{isrc}"        # Priority 1: Exact studio ISRC match on Deezer
      - "ytsearch:\"{isrc}\""  # Priority 2: Direct ISRC track search on YouTube
      - "ytsearch:{query}"     # Priority 3: Sanitized artist + title query
      - "scsearch:{query}"     # Priority 4: SoundCloud streaming fallback
      - "bcsearch:{query}"     # Priority 5: Bandcamp catalog fallback

    youtube:
      oembed: true             # Lightweight metadata resolution fallback (bypasses datacenter bot blocks)
      mirror: true             # Automatic audio mirror fallback when direct playback is restricted
      mirrorProviders:
        - "ytmsearch:%QUERY%"
        - "scsearch:%QUERY%"
      localDiskCache: true
      diskCachePath: "youtube-cache"
      maxDiskCacheMb: 10240
      cipherUrl: "https://cipher.kikkia.dev"
      cookieFile: "ytburner.txt"
      potokenUrl: "https://potoken-generator.vercel.app/token"

    spotify:
      countryCode: "US"
      playlistLoadLimit: 6
      albumLoadLimit: 6
      resolveArtistsInSearch: true

    flowerytts:
      voice: "en-US-Standard-A"
      speed: 1.0

    amazonmusic:
      apiUrl: "https://amazon-music-api-dun.vercel.app/api"
      playlistLoadLimit: 50
      albumLoadLimit: 50
      artistLoadLimit: 50

---

Anti-Throttling Subsystems

Rolling SAPISIDHASH Header Generation

For nodes hosted on hostile datacenter networks (Hetzner, OVH, DigitalOcean, Pterodactyl), provide your burner cookie in ytburner.txt or configure cookieFile: "ytburner.txt".

SolaceAudio computes real-time cryptographic SAPISIDHASH headers in memory for every outgoing request to WEB_REMIX, ensuring uninterrupted direct audio extraction without bot challenge penalties.

Resilient Direct URL Ingestion & oEmbed Resolution

When direct YouTube links are passed to Lavalink on datacenter IPs, YouTube's /youtubei/v1/player endpoint frequently blocks metadata requests without valid cookies or PoTokens. SolaceAudio solves this using an autonomous multi-tier fallback:

1. Lightweight oEmbed Resolution: Fetches title, author, and channel metadata via public oEmbed endpoints without triggering bot friction or requiring authentication.
2. Multilingual Script Normalization: Cleans title noise tags while preserving full Unicode scripts (Devanagari, Gurmukhi, Tamil, Japanese, Cyrillic, Arabic, etc.) and vowel marks (matras).
3. Deterministic Mirror Selection: If direct streaming fails due to datacenter IP restrictions, SolaceAudio automatically resolves and scores mirror candidates across YouTube Music and SoundCloud, preventing generic audio degradation.

Proof-of-Origin Token (PoToken) Routing

Bypass HTTP 403 Forbidden errors and bot friction natively using dynamic auto-rotated PoTokens:

Managed High-Availability Endpoint

potokenUrl: "https://potoken-generator.vercel.app/token"

Private Cluster Deployment

Deploy an isolated token generator directly to your infrastructure using our automated template:

Source repository: Nex-Devz/potoken-generator

---

🎧 Amazon Music Metadata API

SolaceAudio mirrors Amazon Music track, album, playlist, and community playlist metadata through our official high-availability serverless API adapter.

Public Endpoint

apiUrl: "https://amazon-music-api-dun.vercel.app/api"

Self-Hosting (Optional)

Deploy your own isolated Amazon Music metadata adapter to Vercel:

Source repository: Nex-Devz/amazon-music-api

---

Scoring Pipeline

To avoid incorrect tracks and poor audio rips, SolaceAudio runs all mirror candidates through a mathematical validation pipeline:

flowchart LR
    A[Raw Query] --> B[Metadata Sanitizer]
    B --> C[Duration Delta Filter]
    C --> D[Penalty Vector Analysis]
    D --> E[Optimal Stream Resolution]

Loading

1. Metadata Normalization: Strips audio pollution tokens including (Official Music Video), [Remastered 2024], 4K, ft., and punctuation discrepancies.
2. Duration Delta Validation: Matches candidate duration against source track length. Results within a $\pm 2$ second delta receive highest confidence ranking.
3. Penalty Vector Filtering: Applies aggressive down-ranking penalties to terms such as live, acoustic, cover, slowed, reverb, and karaoke unless explicitly part of the source title.

---

Management Endpoints

Contextual Autoplay Recommendations

Query algorithmic track recommendations based on the active session player buffer:

GET /v4/sessions/{sessionId}/players/{guildId}/recommendation?limit=10

Synchronized Lyrics Subsystem

Multi-provider lyrics engine aggregating LRCLIB (public time-synced LRC), Deezer GraphQL, Genius, and Spotify:

# Fetch lyrics for currently playing track in guild
GET /v4/sessions/{sessionId}/players/{guildId}/lyrics

# Direct metadata lookup with timestamp alignment
GET /v4/lyrics?track={trackName}&artist={artistName}&duration={durationMs}

# Fuzzy multi-source lyrics search
GET /v4/lyrics/search?query={searchQuery}

Native SponsorBlock Segments

Manage YouTube segment skipping directly through Lavalink REST endpoints:

# Fetch skipped segments for currently active YouTube track
GET /v4/sessions/{sessionId}/players/{guildId}/sponsorblock

# Update enabled categories for dynamic segment skipping
POST /v4/sessions/{sessionId}/players/{guildId}/sponsorblock
Content-Type: application/json

{
  "enabled": true,
  "categories": ["sponsor", "selfpromo", "interaction", "intro", "outro"]
}

Real-Time Audio DSP Processing

• Voice Auto-Ducking: High-performance FloatPcmAudioFilter providing seamless gain attenuation when voice activity is detected, ramping back to unity gain artifact-free.
• Silence Trimming: Continuous exponential moving average (EMA) energy detector that eliminates awkward lead-in dead air and flags trailing silence for instantaneous queue transitions.

---

Credits & Acknowledgements

• SlugYZeon by xylen-py — Original multi-module architecture, audio source handlers, and configuration from which substantial portions of this project are derived. Licensed under the Apache License, Version 2.0.
• saraansx — Spotify metadata architecture and nuance.json reference schema.
• NodeLink by PerformanC — YouTube VisionOS client stream implementation concepts.
• Official Repository — Maintained at Nex-Devz/SolaceAudio.

Attribution Notice: SolaceAudio is a derivative work based on SlugYZeon, Copyright (c) xylen-py, and is used and distributed in accordance with the Apache License, Version 2.0. Original copyright and attribution notices are retained. See the LICENSE NOTICE section for details.

---

License

This project is licensed under the Apache License, Version 2.0.