Professional Audio Engine
Audience: End users and technical evaluators Last Updated: 2026-04-04 Version: 2.0.0
Overview
Llamafin's audio engine is a professional-grade playback system built on the Web Audio API. It delivers studio-quality audio processing with features typically found only in dedicated desktop audio players, all within a cross-platform application.
Audio Processing Pipeline
Signal Chain Architecture
Every audio track passes through a sophisticated processing chain:
Audio Source → Preamp → 10-Band EQ → Stereo Width → Balance → Volume → Limiter → Analyser → Output
What This Means: Each stage applies specific audio transformations to deliver the best possible sound quality while giving you complete control over the audio characteristics.
10-Band Graphic Equalizer
Precision Frequency Control
Llamafin features a professional 10-band equalizer covering the full audible spectrum:
| Band | Frequency | Audio Range | What It Controls |
|---|---|---|---|
| 1 | 60 Hz | Sub-bass | Deep bass you feel more than hear |
| 2 | 170 Hz | Bass | Bass guitar, kick drum fundamental tones |
| 3 | 310 Hz | Low-mid | Warmth and fullness of instruments |
| 4 | 600 Hz | Mid-range | Vocal presence and clarity |
| 5 | 1000 Hz | Mid-range | Instrument definition and texture |
| 6 | 3000 Hz | Upper-mid | Vocal intelligibility and attack |
| 7 | 6000 Hz | Presence | Brightness and articulation |
| 8 | 12000 Hz | Brilliance | Air and sparkle |
| 9 | 14000 Hz | Brilliance | Cymbal shimmer and detail |
| 10 | 16000 Hz | Ultra-high | Fine detail and spatial cues |
16 Built-in Presets
Quick-access presets for different music genres and listening environments:
| Preset | Best For | Characteristics |
|---|---|---|
| Default | Neutral listening | Flat response, no colouration |
| Classical | Orchestral, acoustic | Enhanced hall ambience |
| Club | Dance, electronic | Strong bass and crisp highs |
| Dance | Upbeat, rhythmic | Punchy bass, clear mids |
| Full Bass | Bass-heavy genres | Elevated low frequencies |
| Full Bass & Treble | V-shaped response | Exciting, dynamic sound |
| Full Treble | Detail-focused listening | Enhanced clarity and air |
| Laptop | Built-in speakers | Optimised for small speakers |
| Live | Concert recordings | Simulates live environment |
| Party | Background music | Full-range, crowd-pleasing |
| Pop | Popular music | Vocal-forward, punchy |
| Reggae | Reggae, ska | Relaxed bass, smooth highs |
| Rock | Rock, metal | Aggressive mids, tight bass |
| Ska | Ska, punk | Bright, energetic |
| Soft | Jazz, acoustic | Smooth, warm response |
| Soft Rock | Mellow rock | Balanced, easy listening |
| Techno | Electronic, synth | Deep bass, crisp highs |
Custom Equalizer
Create and save your own sound signature:
- Each band adjustable from -12 dB to +12 dB
- Fine control over frequency response
- Save custom profiles for different headphones or speakers
Bass & Treble Controls
Simplified tone controls for quick adjustments:
Bass Control:
- Adjusts the three lowest frequency bands (60Hz, 170Hz, 310Hz)
- Applies graduated slope: deepest bass gets full adjustment, higher bass bands get partial
- Range: -12 dB to +12 dB
Treble Control:
- Adjusts the four highest frequency bands (6000Hz, 12000Hz, 14000Hz, 16000Hz)
- Graduated application: highest frequencies get full adjustment
- Range: -12 dB to +12 dB
Stereo Imaging
Stereo Panning (Balance)
Control the left-right balance of audio:
- Range: -1 (full left) to +1 (full right), 0 is centre
- Use Cases:
- Compensate for off-centre listening position
- Adjust for hearing impairment in one ear
- Correct imbalanced speaker systems
Stereo Width (Haas Effect)
Advanced spatial audio processing using the Haas effect:
How It Works:
- One channel is delayed by up to 15 milliseconds relative to the other
- Creates perception of wider or narrower soundstage
- Does not affect frequency response
Width Settings:
| Setting | Value | Effect |
|---|---|---|
| Narrow | 0 | Mono-compatible, centered sound |
| Normal | 1 | Original stereo image |
| Wide | 1.5 | Expanded soundstage |
| Ultra Wide | 2 | Maximum spatial expansion |
Best Uses:
- Headphones: Wider settings create more immersive experience
- Speakers: Normal setting for proper stereo imaging
- Mono systems: Narrow setting ensures compatibility
Loudness normalisation
ReplayGain Support
Automatic volume leveling across your entire library:
The Problem:
- Different albums have different mastering levels
- You constantly adjust volume between tracks
- Modern "loudness war" recordings are much louder than older recordings
The Solution:
- Llamafin analyses integrated loudness of each track
- Automatically adjusts playback volume to match a standard level
- Standard target: -14 LUFS (Loudness Units Full Scale)
How It Works:
- Track's loudness measured from sonic analysis data
- normalisation gain calculated to reach -14 LUFS target
- User preamp gain added (if configured)
- Total gain applied to playback chain
Example:
- Track A mastered at -8 LUFS (loud): Reduced by 6 dB
- Track B mastered at -18 LUFS (quiet): Increased by 4 dB
- Result: Both tracks play at same perceived loudness
User Preamp
Fine-tune the overall output level:
- Adjusts gain before it reaches the equalizer
- Range: -12 dB to +12 dB
- Combined with loudness normalisation for perfect levels
- Prevents clipping when using EQ boost
Audio Limiter
Distortion Prevention
High-ratio limiter prevents distortion at high volumes:
Configuration:
- Ratio: 12:1 (enabled) or 1:1 (disabled)
- Threshold: -10 dB
- Knee: 10 dB (soft knee for transparent limiting)
- Attack: 0 ms (instant response)
- Release: 0.25 seconds
When to Use:
- High-volume listening: Prevents peaks from distorting
- Heavy EQ boost: Compensates for increased signal levels
- Dynamic music: Handles sudden loud passages gracefully
Transparent Limiting:
- Soft knee characteristic means gradual onset of limiting
- Fast attack catches transients before they clip
- Short release returns to normal quickly
- You hear the music, not the limiter working
Gapless Playback
Seamless Track Transitions
No gaps between consecutive tracks - essential for:
- Live albums: Continuous concert experience
- Classical music: Multi-movement works flow naturally
- Concept albums: Albums designed as continuous listening
- DJ mixes: Continuous mixes without interruption
How It Works
Three-Track Pool System:
- Current Track: What you're listening to now
- Next Track: Pre-loaded and ready for instant playback
- Previous Track: Cached for instant skip back
Benefits:
- Instant track changes (no loading delay)
- Crossfade capability (smooth transitions)
- Previous/next always available
Smart Stream Pool
Llamafin maintains multiple audio streams for optimal performance:
Pool Size: 6 concurrent streams (configurable 4-10)
Stream Roles:
- Current: Actively playing
- Next: Preloaded and ready
- Previous: Cached for instant return
- Spare: Available for allocation
- Preview: Isolated 30-second previews
Crossfade (Sweet Fades)
Smooth Track Transitions
Automatically blend between tracks for a polished listening experience:
How It Works:
- As current track nears end, preloaded next track is ready
- Outgoing track fades out while incoming track fades in
- Linear fade curves for natural sound
- Configurable fade duration
Benefits:
- Professional DJ-style transitions
- Eliminates abrupt track changes
- Creates continuous listening flow
- Perfect for parties or background music
Smart Behaviour:
- Won't crossfade on last track of queue
- Respects track boundaries
- Automatically manages stream pool for instant transitions
Audio Streaming
Three Streaming Strategies
Llamafin intelligently selects the best streaming method:
| Strategy | When Used | Characteristics |
|---|---|---|
| Local | File already downloaded | Instant playback, no network needed |
| Direct | Server supports direct streaming | Original quality, no server processing |
| Transcode | Format conversion needed | Server converts to compatible format |
HLS Streaming Support
For adaptive bitrate streaming:
- HLS.js Integration: Professional HTTP Live Streaming
- Adaptive Quality: Automatically adjusts to network conditions
- Buffer Management: Intelligent pre-buffering prevents dropouts
- Live Streaming: Supports live radio and broadcasts
Offline Playback
Downloaded music plays seamlessly:
- Local File Detection: Recognises downloaded content
- No Network Required: Complete offline playback
- Format Support: All downloaded formats supported
- Self-Healing: Detects stale local data and recovers automatically
Track Previews
30-Second Previews
Sample tracks before committing to full playback:
Preview Features:
- Isolated playback (doesn't affect queue)
- 30-second duration (28 seconds + 2-second fade-out)
- Countdown timer displayed
- Can stop preview early
- Uses separate audio stream
Use Cases:
- Browse albums quickly
- Discover new music
- Verify track is what you want
- Avoid downloading unwanted tracks
Playback Controls
Standard Controls
| Control | Function |
|---|---|
| Play | Start or resume playback |
| Pause | Pause at current position |
| Stop | Stop playback and clear queue |
| Seek | Jump to any position in track |
| Skip Forward | Quick skip ahead (configurable) |
| Skip Backward | Quick skip back (configurable) |
Advanced Controls
| Control | Function | Range |
|---|---|---|
| Volume | Master volume level | 0% to 100% |
| Playback Rate | Speed control | 0.5x to 2.0x |
| Balance | Left/right stereo pan | -1 (left) to +1 (right) |
| Stereo Width | Soundstage width | 0 (mono) to 2 (ultra-wide) |
Audio Output Devices
Multi-Device Support
Select different audio output devices:
Desktop (Electron):
- System audio device enumeration
- Select specific output devices
- USB audio interface support
- Bluetooth device selection
- Transport type information (USB, Bluetooth, Analog)
Mobile (Capacitor):
- Native device selection
- Bluetooth headset support
- Speaker/earpiece switching
- Wired headphone detection
Device Persistence
Your device choice is remembered:
- Selected device saved to settings
- Automatically applied on next playback
- Reverts to default if device unavailable
Visualisation System
Real-Time Audio Analysis
Extract frequency data for visual displays:
Technical Details:
- FFT Size: 512 samples (256 frequency bins)
- Smoothing: 0.75 time constant for stable display
- Frame Rate: Configurable 30-60 FPS
- Zero Allocation: Reusable buffer for performance
Visualisation Types
Llamafin supports multiple visualizer types:
Butterchurn (MilkDrop):
- Industry-standard music visualizer
- Hundreds of presets available
- GPU-accelerated rendering
- Full-screen immersive mode
Spectrum Analyser:
- Bar graph frequency display
- Real-time frequency response
- Configurable appearance
- Rolling window mode
Performance Optimised:
- Runs outside Angular's zone (no UI interference)
- Single shared loop for all subscribers
- Frame rate control limits CPU usage
- Automatically disabled in background
Audio Context Management
Browser Autoplay Policy
Modern browsers block audio until user interaction:
How Llamafin Handles This:
- AudioContext created in suspended state
- First user gesture (click/tap) activates audio
- Pending playback requests automatically retry
- Clear messaging if interaction needed
Seamless Experience:
- You never see autoplay errors
- Audio starts immediately after first interaction
- Background tabs may require re-activation
Background Playback
WebView Protection
Keep audio playing even when app is in background:
Silent Audio Technique:
- Inaudible silent audio stream keeps OS audio pipeline active
- Prevents system from suspending playback
- Volume: 0.0001 (completely inaudible)
- Continuous loop of 10-second silence file
Smart Activation:
- Active playback always protects WebView
- Car mode always enables protection
- Paused state has grace period
- User configurable in advanced settings
Engagement Features
Continue Listening Notifications
Smart reminders to come back to your music:
How It Works:
- When you pause playback, notification scheduled
- 24-hour delay before notification appears
- Includes track artwork and title
- Deep link returns you to current track
- Cancelled automatically when you resume
Benefits:
- Re-engage with your music library
- Remind you what you were listening to
- Easy return to your listening session
Performance Optimizations
Zero-Allocation Frequency Data
Visualisation data extraction optimised for performance:
Technique:
- Single buffer allocated once
- Same reference returned every frame
- No garbage collection pressure
- 60 FPS sustainable
RequestAnimationFrame Progress Tracking
High-resolution time updates:
- Per-stream RAF loop (not setInterval)
- Synchronised with display refresh rate
- Smooth, jitter-free progress updates
- Only runs when audio context is active
Stream Pool Management
Dynamic pool resizing:
- Default 6 streams for optimal performance
- Configurable from 4 to 10 streams
- Changes applied without interrupting playback
- Success notification when pool resized
Error Handling
Robust Playback
Multiple layers of protection:
Stale Event Protection:
- Validates track ID before applying updates
- Prevents old events from corrupting current state
- Essential for gapless playback reliability
Crossfade Guards:
- Ignores pause events during crossfade
- Prevents interrupted transitions
- Ensures smooth track changes
Self-Healing:
- Detects stale local track data
- Automatically recovers and retries
- Logs warnings for debugging
- User notified of recovery
Stream Allocation:
- Graceful fallback when pool exhausted
- Logs critical "pool exhausted" warnings
- Continues playback with available resources
- Adjustable pool size prevents exhaustion
Audio Codec Support
Decoding Capabilities
Llamafin supports all major audio formats:
Via Direct Streaming:
- MP3, AAC, OGG, FLAC, WAV, ALAC, WMA
- Whatever Jellyfin server supports
Via Transcoding:
- Any format Jellyfin can transcode
- Server-side conversion to compatible format
- Configurable transcoding quality
Local Playback:
- All downloaded formats supported
- No additional codec requirements
- Full offline capability
Technical Specifications
| Specification | Value |
|---|---|
| EQ Bands | 10 (60Hz - 16kHz) |
| EQ Presets | 17 built-in + custom |
| EQ Range | -12 dB to +12 dB per band |
| Bass/Treble Range | -12 dB to +12 dB |
| Stereo Width Range | 0 (mono) to 2 (ultra-wide) |
| Balance Range | -1 (left) to +1 (right) |
| Playback Rate Range | 0.5x to 2.0x |
| Limiter Ratio | 12:1 (enabled) / 1:1 (disabled) |
| Limiter Threshold | -10 dB |
| Limiter Attack | 0 ms |
| Limiter Release | 250 ms |
| ReplayGain Target | -14 LUFS |
| Analyser FFT Size | 512 (256 bins) |
| Analyser Smoothing | 0.75 |
| Visualisation FPS | 30-60 (configurable) |
| Stream Pool Size | 6 (configurable 4-10) |
| Preview Duration | 30 seconds (28s + 2s fade) |
| Haas Delay Max | 100ms |
| Haas Delay Per Unit | 15ms |
| Silent Track Volume | 0.0001 (-80 dB) |