Settings & customisation
Audience: End users and technical evaluators Last Updated: 2026-04-04 Version: 2.0.0
Overview
Llamafin provides extensive customisation options across 10 settings categories, allowing you to tailor every aspect of the application to your preferences, from appearance and audio playback to download behaviour and notifications.
Settings Categories
10 Areas of customisation
| Category | What You Control | Complexity |
|---|---|---|
| Account | User profile and preferences | Simple |
| Source | Server connections | Simple |
| Language | App language | Simple |
| Appearance | Themes, backgrounds, fonts, UI | Extensive |
| Playback | Audio effects, EQ, autoplay | Moderate |
| Music Quality | Streaming quality | Simple |
| Downloads | Download behaviour, caching, analysis | Extensive |
| Notifications | Notification preferences | Moderate |
| Advanced | Debug, caching, scheduler | Moderate |
| About | Credits, licenses | Simple |
Account Settings
Your Profile
What's Stored:
- Jellyfin username
- User ID
- Account capabilities (password, auto-login)
- Last login and activity dates
- User configuration and policy
Management:
- View-only (managed by Jellyfin server)
- Cleared automatically on logout
- Synced with server on login
Server Source Settings
Managing Server Connections
Add Server:
- Enter server name and address
- Test connection
- Save configuration
- Multiple servers can be stored
Server Configuration:
- Name: Friendly name for the server
- Address: Full URL (e.g.,
http://192.168.1.100:8096) - Active Status: Which server is currently connected
- Last Accessed: Timestamp of last connection
Server Operations:
| Operation | What It Does |
|---|---|
| Add | Store new server configuration |
| Edit | Update address or name |
| Remove | Delete server configuration |
| Activate | Switch to this server |
| Deactivate All | Clear active status |
Automatic Management:
- Last used server remembered
- Auto-activates on successful login
- Connection history tracked
Language Settings
Multi-Language Support
Supported Languages:
- English (default)
- Spanish
- French
- German
- Italian
- Portuguese
- And many more
Language Features:
- Full interface translation
- Dynamic switching (no restart needed)
- Country flag display
- Native language descriptions
How to Change:
- Go to Settings → Language
- Select your preferred language
- Interface updates immediately
Appearance Settings
Theme Selection
Available Themes:
| Theme | Description | Best For |
|---|---|---|
| Dark | Default dark theme | Low-light environments |
| Light | Clean light theme | Daytime use |
| Black | Pure black (AMOLED) | OLED/AMOLED displays |
| White | Pure white | Maximum brightness |
System Theme Tracking:
- Automatically follows OS theme
- Can be disabled for manual control
- Switches dynamically
Background customisation
Background Styles:
| Style | Effect |
|---|---|
| Flat | Solid colours, no blending |
| Smooth | Gradual colour transitions |
| Ultra Blur | Heavy blur for soft backgrounds |
Gradient Types:
- Linear
- Radial
- Conic
- Repeating patterns
Colour Control:
- Up to 12 colours per background
- Adjustable colour stops
- Direction control (17 options)
- Blur amount adjustment
Background Presets:
- Theme-matched presets available
- One-click application
- Custom backgrounds supported
- Per-theme background memory
Typography
Font Selection:
- Default: Inter font family
- System font fallbacks
- Platform-optimised choices
- Accessibility considerations
Audio Visualisations
Enable/Disable:
- Toggle Visualisations on/off
- Frame rate control (25-60 FPS)
- Performance impact management
Player Appearance
Player Controls (20+ options):
| Setting | Options | Description |
|---|---|---|
| colourise Elements | On/Off | Theme-matched control colours |
| Show Codec Rating | On/Off | Display audio format info |
| Show Volume Control | On/Off | Volume slider visibility |
| Side-by-Side Layout | On/Off | Cover art and info side-by-side |
| Show Album Year | On/Off | Display release year |
| Show Fullscreen Button | On/Off | Fullscreen toggle button |
| Show Play Speed | On/Off | Playback speed control |
| Long Form Controls | On/Off | Larger touch targets |
| Show Quick Skip | On/Off | Skip buttons |
| Quick Skip Times | 5-30 seconds | Back/forward skip duration |
| Seekbar Style | Default, Chameleon | Seekbar appearance |
| Background Style | Cover, Gradient | Player background |
| Layout Position | Cover left/right | Side-by-side arrangement |
| Scale Factor | 0.8-1.2 | Overall size scaling |
| Cover Art Size | 18-26% | Album artwork size |
| Cover Art Margin | 0-10% | Top margin adjustment |
| Vertical Spacing | Compact/Default/Relaxed | Element spacing |
| Button Size | 2.5-4 rem | Control button size |
| Turntable Theme | Modern/Classic | Spinning record style |
| Turntable Performance | Auto/Low/High | Animation quality |
Home Screen customisation
Section Order:
- Recently played
- Latest additions
- Frequently played
- Discover hero section
Order Values:
- Each section has order number (1, 2, 3...)
- Lower number = higher on page
- Can hide sections by setting order to 0
Library View Settings
Display Mode:
- List view (default)
- Grid view
- Grid with carousel (optional)
Glass Style:
- Flat (no glass effect)
- Frosted glass (low quality)
- Frosted glass (medium quality)
- Frosted glass (high quality)
Rating Systems
Available Systems:
| System | Stars | Half Stars | Best For |
|---|---|---|---|
| One | 1 (like/dislike) | No | Simple preference |
| Five | 5 | No | Standard rating |
| Five-Half | 5 | Yes | Precise rating |
Additional Display Options
| Option | What It Does |
|---|---|
| Album Codec Badges | Show audio format badges |
| Album Popular Tracks | Show popular tracks on album page |
| Overflow Text | Handle long text (truncate/marquee) |
| Car View | Simplified driving interface |
| Keep Screen On | Prevent sleep on player page |
Animation & Performance
Skeleton Animations:
- Shimmer
- Pulse
- Rainbow wave
- Scanline
- Static
- None (instant display)
Performance Modes:
- Auto (recommended)
- Low (conservative)
- High (maximum quality)
Applies to:
- Rotary dial interactions
- Active download displays
Camera Cutout Compensation
Presets:
- Auto (detected automatically)
- Manual override
- Custom offset (adjustable)
Purpose: Prevents UI obstruction by notches/cutouts
Rolling Window (Pagination)
Preset Options:
- Default (25 items)
- Small (10 items)
- Medium (50 items)
- Large (100 items)
- Custom
Settings:
- Page size: Items loaded per request
- Max display: Maximum items in memory
- Affects performance and memory usage
Spectrum Visualizer
Preset Options:
- Auto (recommended)
- Custom
Custom Settings:
- Bar count: 16-64 bars
- Update interval: 16-100ms
- Colour scheme
- Animation style
EQ Fader
Preset Options:
- Auto (recommended)
- Custom
Custom Settings:
- VU meter throttle rate: 16-100ms
- Display style
- Colour scheme
Playback Settings
Audio Output
Device Selection:
- Default system output
- USB audio interfaces
- Bluetooth devices
- HDMI/DisplayPort audio
Settings Persist: Your choice is remembered across sessions
Loudness Leveling
What It Does:
- Normalises volume across tracks
- Prevents loudness jumps between songs
- Based on ReplayGain standard
Configuration:
- Enable/disable
- Target loudness: -14 LUFS (standard)
- Works with sonic analysis data
Sweet Fades (Crossfade)
Smooth Track Transitions:
- Enable/disable crossfade
- Duration: 1-10 seconds
- Default: 5 seconds
Benefits:
- Professional DJ-style transitions
- Eliminates abrupt track changes
- Creates continuous listening flow
Equalizer
10-Band Graphic EQ:
- 60 Hz to 16 kHz coverage
- -12 dB to +12 dB per band
- 16 built-in presets
- Custom EQ creation
Built-in Presets:
| Preset | Best For |
|---|---|
| Default | Flat response |
| Classical | Orchestral music |
| Club | Dance, electronic |
| Rock | Rock, metal |
| Pop | Popular music |
| Jazz | Jazz, acoustic |
| And 10 more... | Various genres |
Custom Presets:
- Create your own
- Save with custom name
- Unlimited custom presets
- Easy switching
Tone Controls
Bass Control:
- Range: -12 dB to +12 dB
- Affects lowest 3 frequency bands
- Graduated application
Treble Control:
- Range: -12 dB to +12 dB
- Affects highest 4 frequency bands
- Graduated application
Preamp
Purpose: Adjust overall output level
Range: 0-6 dB
Use Cases:
- Compensate for quiet recordings
- Prevent clipping with heavy EQ
- Match output to amplifier
Limiter
What It Does:
- Prevents distortion at high volumes
- High-ratio compression (12:1)
- Transparent operation
When to Enable:
- High-volume listening
- Heavy EQ usage
- Dynamic music with loud passages
Stereo Width
Range: 0 (mono) to 2 (ultra-wide)
Effects:
- 0: Mono-compatible
- 1: Normal stereo
- 1.5: Expanded soundstage
- 2: Maximum spatial expansion
Best For Headphones: Wider settings create immersive experience
Audio Effects Master Switch
Bypass Toggle:
- Enable/disable all audio effects
- Quick comparison of processed vs original
- Useful for troubleshooting
Radio Settings
External Media:
- Include external/radio content
- Degrees of separation: Limited or unlimited
Autoplay Settings
| Setting | Options | Description |
|---|---|---|
| Autoplay on Start | On/Off | Resume playback on app open |
| Enabled | On/Off | Master autoplay switch |
| Album Direction | Next/Previous | Album sequence direction |
| Add to Recent Plays | On/Off | Track autoplay in history |
Stream Pool
Purpose: Number of concurrent audio streams
Preset Options:
- Conservative: 4 streams
- Balanced: 6 streams (default)
- Aggressive: 8-10 streams
Affects: Gapless playback quality and memory usage
Music Quality Settings
Streaming Quality
WiFi Quality:
- Auto (LlamaSense decides)
- Maximum (original quality)
- 2048 kbps
- 1024 kbps
- 320 kbps
- 256 kbps
- 192 kbps
- 160 kbps
- 128 kbps
- 96 kbps
- 64 kbps
Cellular Quality:
- Same options as WiFi
- Default: 128 kbps (conservative)
- Auto uses LlamaSense to decide
Auto Mode (LlamaSense):
- Measures network speed
- Selects optimal quality automatically
- Balances quality vs data usage
Conversion Bitrate
Purpose: Quality for transcoded streams
Options: 64, 96, 128, 160, 192, 256 kbps
Default: 128 kbps
Downloads Settings
Download Quality
WiFi Quality:
- Auto (LlamaSense)
- Maximum
- 320 kbps to 64 kbps options
Cellular Quality:
- Same options
- Auto recommended
LlamaSense Smart Downloads
Smart Downloads:
- Enable/disable automatic quality selection
- Algorithm: Median (default), Average, or Weighted
- Uses historical network speed data
Prefer Downloaded Media:
- Always: Use offline copies when available
- Cellular: Prefer offline only on cellular
- Never: Always stream
Download Behaviour
| Setting | Options | Description |
|---|---|---|
| Downloads on Cellular | On/Off | Allow cellular downloads |
| Download Location | Internal/External | Storage location |
| Refresh on Connect | On/Off | Check for updates |
| Download Lyrics | On/Off | Auto-download lyrics |
Smart Workers
What They Do:
- Background processing for downloads
- Prevents UI freezing
- Automatic thread selection
Configuration:
- Enable/disable
- Algorithm: Median, Average, Weighted
- Thresholds: Auto or numeric (MB)
- Concurrent downloads threshold
- Transcode threshold
Retry Logic
| Setting | Default | Description |
|---|---|---|
| Max Item Retries | 3 | Retries per failed item |
| Max Consecutive Failures | 3 | Stops after this many failures |
Concurrent Download Config
| Setting | Default | Description |
|---|---|---|
| Pool Limit | 5 | Concurrent downloads |
| Chunk Size | 5 MB | Size per chunk |
| Max Retries | 3 | Retries per chunk |
Transcode Download Config
| Setting | Default | Description |
|---|---|---|
| Pool Limit | 3 | Concurrent segment downloads |
| Max Retries | 3 | Retries per segment |
Sonic Analysis Settings
Run Mode:
- Disabled: Never run analysis
- Auto: LlamaSense decides
- Always: Analyse all downloads
- Post-Container Completion: Analyse after download completes
Smart Analysis:
- Enable/disable automatic analysis
- Algorithm selection (Median/Average/Weighted)
Execution:
- Automatic (recommended)
- Native
- Web Worker
- Main Thread
Limits:
- Max file size: 10-100 MB (default: 50 MB)
- Max duration: 1-10 minutes (default: 5 min)
- Compute spectrogram: On/Off
Advanced Settings Display
Show Advanced:
- Toggle advanced settings visibility
- Simplifies interface for most users
- Full control when enabled
Notifications Settings
Master Switch
Notifications Enabled:
- Master on/off toggle
- Disables all notifications when off
- Granular control when on
Library & Content Notifications
| Notification | What It Does |
|---|---|
| New Library Releases | New albums added to server |
| New Playlist Publications | New playlists available |
| Favorite Artist Releases | New music from favorite artists |
| Trending on Server | Popular content on your server |
Engagement & Discovery Notifications
| Notification | What It Does |
|---|---|
| Recommendations | Music suggestions for you |
| Re-engagement Reminders | Come back to your music |
| Continue Listening Reminders | Resume paused sessions |
| Playback Summaries | Listening activity summaries |
| Listening Streaks | Track your listening streaks |
| Queue Suggestions | Suggested tracks for queue |
App & System Notifications
| Notification | What It Does |
|---|---|
| Download Status | Download completion/failure |
| App Updates | New version available |
| Storage Warnings | Low disk space alerts |
| Lyrics Available | Lyrics found for current track |
| Connection Status | Server connection changes |
| Sync & Backup Status | Backup completion status |
Advanced Settings
Player Name
Purpose: Device identifier on network
Default: llamafin
Use Case: remote device control identification
Remote Control Settings
| Setting | Default | Description |
|---|---|---|
| Enable Remote Control | Off | Allow remote control |
| Discoverable | Off | Appear in device discovery |
| Hash User Identity | On | Anonymize user on network |
Caching Settings
Master Switch:
- Caching enabled/disabled
WiFi Caching:
- Disabled
- Next track only
- 5-40 tracks
- Unlimited
Cellular Caching:
- Same options
- More conservative defaults
Cache Size Limit:
- 128 MB to 10 GB
- Unlimited option
Network Speed:
- Unlimited
- Custom limit (Mbps)
Audio Interface
Decoder Selection:
- Auto (recommended)
- AAudio (Android)
- Other platform-specific options
Quick Access Settings
| Setting | Default | Description |
|---|---|---|
| One-Tap Track Plays | Off | Tap to play immediately |
| Show Preview Buttons | Off | 30-second preview buttons |
| Show Full Player | Off | Auto-open full player |
| Search All Libraries | Off | Search across all servers |
| Sync Recent Plays | Off | Sync play history to server |
Debugging Settings
Log Level:
- DEBUG
- INFO (default)
- WARN
- ERROR
- NONE
Console Logs in Production:
- Force enable for troubleshooting
- Disabled by default
History Caps:
- Log history: 1,000-100,000 entries (default: 10,000)
- Metrics history: 100-10,000 entries
- Network speed history: 100-1,000 entries
Debug Overlays (Mutually Exclusive):
| Overlay | What It Shows |
|---|---|
| Performance | FPS, render times |
| Player Debug | Playback state |
| Memory | Memory usage |
| FPS Counter | Frame rate |
| Consolidated | All metrics combined |
| Stream Pool | Audio stream status |
LlamaSense Simulator:
- Simulate network conditions
- Test quality selection
- Development tool
Scheduler Settings
| Setting | Default | Description |
|---|---|---|
| Max Concurrent Jobs | 1 | Simultaneous background jobs |
| Max Task Retries | 3 | Retries per failed task |
Delete Functionality
Enable Delete:
- Off by default (safety)
- Enables song/playlist deletion
- Confirmation dialogues required
Haptics
Haptic Feedback:
- Enable/disable tactile feedback
- Platform-dependent support
- Enhances touch interactions
Offline Mode
Force Offline:
- Emergency offline mode
- Bypasses network checks
- Uses only cached content
About Settings
Credits & Information
Contents:
- Thank you messages
- Translation credits
- Open source licenses
Dynamic Content:
- Loaded from server
- Updated with app versions
- Acknowledges contributors
Settings Persistence
Automatic Saving
How It Works:
- All changes saved automatically
- 1-second debounce prevents excessive writes
- Batched for efficiency
What's Saved:
- All 10 settings categories
- Server configurations
- Custom presets (EQ, backgrounds)
- Playback preferences
Settings Migration
Automatic Updates:
- Database version tracked (currently v49)
- Automatic migration on version change
- Preserves your preferences
- Shows migration message during update
Migration Safety:
- Backward compatible
- Non-destructive
- Logged for debugging
- Can be forced via advanced settings
Reset Settings
Full Reset:
- Available in Advanced settings
- Resets ALL settings to defaults
- Clears custom presets
- Persists reset to storage
Account Clear:
- Separate from full reset
- Clears only account data
- Triggered on logout
Interdependent Settings
Automatic Validation
LlamaSense Auto-Disable:
- If Smart Downloads enabled but quality is NOT set to Auto
- Automatically disables Smart Downloads
- Prevents conflicting settings
Smart Analysis Auto-Disable:
- If Run Mode is NOT Auto but Smart Analysis enabled
- Automatically disables Smart Analysis
- Ensures logical consistency
Smart Workers Auto-Disable:
- If Smart Workers enabled but thresholds are NOT Auto
- Automatically disables Smart Workers
- Maintains configuration integrity
Theme-Background Sync
Automatic Behaviour:
- Changing theme updates background
- Matches preset for that theme
- Enables custom backgrounds flag
- Seamless visual transition
Debug Overlay Exclusivity
Mutual Exclusion:
- Only one debug overlay at a time
- Enabling one disables others
- Prevents performance interference
- Clear visual feedback
Best Practices
Recommended Settings
For Most Users:
- Theme: Dark (or match system)
- Quality: Auto (let LlamaSense decide)
- Downloads: Auto quality, WiFi preferred
- Caching: Enabled, Next track or 10-20 tracks
- Audio Effects: Enabled
- Autoplay: On for continuous listening
For Audiophiles:
- Quality: Maximum
- EQ: Custom tuned to your headphones/speakers
- Loudness Leveling: Enabled (-14 LUFS)
- Limiter: Enabled for high-volume listening
- Stream Pool: Balanced or Aggressive
For Mobile/Cellular:
- Quality: Auto or 128-192 kbps
- Downloads: Block cellular or limit to 128 kbps
- Caching: Next track only or 5-10 tracks
- Smart Workers: Enabled (prevents UI freeze)
For Offline Use:
- Downloads: Maximum quality on WiFi
- Lyrics: Enabled
- Sonic Analysis: Always or Post-Container
- Prefer Downloaded Media: Always
Technical Specifications
| Specification | Value |
|---|---|
| Settings Categories | 10 |
| Appearance Properties | 26 |
| Playback Properties | 14 |
| Downloads Properties | 23 |
| Advanced Properties | 16 |
| Notification Toggles | 16 |
| EQ Bands | 10 |
| EQ Presets | 16 built-in + unlimited custom |
| Background Colours | Up to 12 per background |
| Gradient Directions | 17 |
| Skeleton Animations | 6 |
| Rating Systems | 3 |
| Themes | 4 |
| Migration Stages | 31 |
| Settings Save Debounce | 1 second |
| Database Version | 49 |
| Storage System | IndexedDB |