Sonic Analysis
Audience: End users and technical evaluators Last Updated: 2026-04-05 Version: 2.0.0
Overview
Sonic Analysis is Llamafin's deep audio analysis engine that examines your downloaded music tracks to extract detailed musical and technical information. It analyses BPM (tempo), musical key, loudness, spectral characteristics, and generates visual representations like spectrograms. It also powers the "Sonic Twins" feature that discovers musically similar tracks based on tempo and harmonic compatibility.
Key Concepts
What is Sonic Analysis?
Sonic Analysis works like a musicologist examining each track in your library:
- Musical Analysis: Detects tempo (BPM), musical key, time signature, and rhythm patterns
- Technical Analysis: Measures loudness (LUFS), dynamic range, stereo width, audio quality
- Visual Analysis: Generates spectrograms, chromagrams, and waveform Visualisations
- Smart Matching: Finds "Sonic Twins" - tracks with similar musical characteristics
How It Works
The Analysis Process:
- Download Completion: Analysis starts automatically after a track is downloaded
- Audio Decoding: The audio file is decoded into raw waveform data
- DSP Processing: Digital Signal Processing algorithms extract musical features
- Data Storage: Analysis results saved to the track's metadata
- Visualisation Generation: Heavy Visualisation data (spectrograms) saved separately
- Ready for Use: Analysis data available for playback, matching, and display
Smart Execution:
Llamafin intelligently decides when and how to analyse:
- Battery Aware: Skips analysis on battery power (mobile devices)
- Resource Monitoring: Adjusts processing based on CPU and RAM availability
- Configurable: You control when and how analysis runs
- Non-Blocking: Runs in background without interrupting your experience
What Sonic Analysis Discovers
Musical Properties
| Property | What It Is | Why It Matters |
|---|---|---|
| BPM (Tempo) | Beats per minute - how fast the track is | Match tracks with similar energy, DJ mixing, workout playlists |
| Musical Key | The key the track is in (e.g., C Major, A Minor) | Harmonic mixing, finding compatible tracks |
| Time Signature | Rhythm structure (e.g., 4/4, 3/4) | Understanding rhythmic feel |
| Tempo Confidence | How certain the detection is (0-100%) | Reliability indicator for BPM data |
Technical Properties
| Property | What It Is | Why It Matters |
|---|---|---|
| LUFS (Loudness) | Integrated loudness measurement | Consistent volume across tracks, streaming platform compliance |
| Dynamic Range | Difference between loudest and quietest parts | Audio quality indicator - higher is better |
| Crest Factor | Peak to average ratio | Identifies compressed vs dynamic tracks |
| Stereo Width | How wide the stereo image is | Spatial quality assessment |
| Phase Correlation | Mono compatibility check | Ensures playback compatibility |
Spectral Properties
| Property | What It Is | Why It Matters |
|---|---|---|
| Spectral Centroid | "Centre of gravity" of frequencies | Timbre characterization (dark vs bright) |
| Zero Crossing Rate | How often signal changes sign | Measure of noisiness/percussiveness |
| Spectral Rolloff | Frequency below which most energy lies | Brightness indicator |
Sonic Twins
Overview
Sonic Twins is Llamafin's smart music discovery feature that finds tracks in your library with similar musical characteristics. It uses both BPM (tempo) and musical key compatibility to score how well tracks match.
How Sonic Twins Works
The Matching Process:
- Select a Track: Open the Sonic Analysis page for any downloaded track
- Find Candidates: System scans all your downloaded tracks
- Score Each Track: Calculates compatibility using BPM and key matching
- Rank Results: Returns top 10 most compatible tracks
- Explore: Click any twin to view its analysis
Scoring System
BPM Matching (60% of score):
| BPM Difference | Score | Compatibility |
|---|---|---|
| ≤ 1% | 100/100 | Perfect tempo match |
| ≤ 3% | 80/100 | Very close tempo |
| ≤ 6% | 50/100 | Reasonable tempo match |
| > 6% | 0/100 | Tempo too different |
Key Matching (40% of score):
Uses the Camelot Wheel system (used by DJs for harmonic mixing):
| Relationship | Score | Description |
|---|---|---|
| Exact Match | 100/100 | Same key and mode |
| Relative Key | 90/100 | Major/minor pair (e.g., C Major ↔ A Minor) |
| Harmonic Shift | 80/100 | Adjacent keys on Camelot wheel |
| Diagonal Boost | 70/100 | Diagonal on Camelot wheel |
| Energy Boost | 60/100 | +2 keys on wheel |
Minimum Threshold: Only tracks scoring above 50/100 are shown as Sonic Twins.
Sonic Twins Use Cases
Smooth Playlist Creation:
- Find tracks that transition naturally
- Maintain consistent energy and mood
- Perfect for parties, workouts, background music
DJ Preparation:
- Identify compatible tracks for mixing
- Plan sets with harmonic flow
- Discover unexpected pairings
Music Discovery:
- Find tracks you didn't know were similar
- Explore your library in new ways
- Connect artists and genres by sound
Visualisations
Spectrogram
A spectrogram shows frequency content over time - like a musical fingerprint:
- X-Axis: Time (start to end of track)
- Y-Axis: Frequency (low to high)
- Colour: Intensity (blue = quiet, red = loud)
Use Cases:
- Identify frequency content and EQ balance
- Spot artifacts and audio issues
- Visual comparison between tracks
- See the full frequency spectrum at once
Viewing Modes:
- Waveform: Traditional amplitude display
- Linear Spectrogram: Frequency spectrum with linear scale
- Logarithmic Spectrogram: Frequency spectrum with log scale (better for music)
- Spectrum Bars: Snapshot of frequency content at a moment
Chromagram
A chromagram shows the 12 musical notes (C, C#, D, ..., B) over time:
- X-Axis: Time
- Y-Axis: Musical pitch class
- Colour: Note intensity
Use Cases:
- See which notes are prominent
- Identify the key and modulations
- Understand harmonic structure
- Visual chord progression tracking
Circle of Fifths
Visual representation of musical key relationships:
- Outer Ring: Major keys (1B-12B in Camelot notation)
- Inner Ring: Minor keys (1A-12A)
- Highlighting: Shows the track's active key and relative key
Technical Metrics Dashboard
LUFS Meter
Shows your track's loudness compared to streaming platform standards:
| Platform | Target LUFS |
|---|---|
| Spotify | -14 LUFS |
| Apple Music | -16 LUFS |
| YouTube | -14 LUFS |
| Tidal | -14 LUFS |
| Amazon Music | -14 LUFS |
| Broadcast | -23 LUFS |
Colour Coding:
- Red: Too loud (above -9 LUFS)
- Green: In range (-14 to -9 LUFS)
- Blue: Too quiet (below -14 LUFS)
Dynamic Range
Measures the difference between the loudest and quietest parts:
| Range | Classification |
|---|---|
| < 6 dB | Compressed (low dynamic range) |
| 6-12 dB | Balanced |
| ≥ 12 dB | Dynamic (high dynamic range) |
Quality Checks
Clipping Detection:
- PASS: No clipping detected
- FAIL: Clipping present (audio distortion)
DC Offset:
- Measures unwanted DC component in audio
- Threshold: 0.001
- High DC offset can cause playback issues
Platform Readiness Score
Scores your track's compatibility with each streaming platform (0-100):
Scoring Penalties:
- Clipping detected: -50 points
- DC offset: -20 points
- Peak too loud: -40 points
- LUFS too loud: -10 points per LU
- LUFS too quiet: -5 points per LU
Status Levels:
- Optimal (≥90, 0 issues): Ready for platform
- Good (≥60): Acceptable with minor issues
- Fail (<60): Significant issues to address
Configuration
Sonic Analysis Settings
Location: Settings → Downloads → Sonic Analysis
| Setting | Options | Description |
|---|---|---|
| Run Mode | Always, Auto, After Download Complete, Disabled | When to run analysis |
| Smart Analysis | Enabled/Disabled | Enable intelligent resource management |
| Execution Mode | Automatic, Native, Web Worker, Main Thread | How analysis is performed |
| Generate Spectrogram | Enabled/Disabled | Create spectrogram Visualisation |
| Max File Size | 10MB, 25MB, 50MB, 100MB | Skip files larger than this limit |
| Max Duration | 1min, 3min, 5min, 10min | Skip tracks longer than this limit |
Run Mode Options
| Mode | Behaviour | Best For |
|---|---|---|
| Always | Analyse every downloaded track | Full analysis library |
| Auto | Smart analysis based on conditions | Balanced approach (recommended) |
| After Download Complete | Analyse only after full container download | Batch processing |
| Disabled | No analysis performed | Save battery and storage |
Smart Analysis (Llamasense)
When enabled, Llamasense intelligently manages analysis:
Automatic Resource Checks:
- Battery: Skips analysis on battery power (mobile devices)
- CPU: Switches to lighter processing if CPU > 90%
- RAM: Switches to lighter processing if free RAM < 200MB
- Platform: Chooses optimal execution method for your device
How Sonic Analysis Works
The Analysis Pipeline
Step 1: Download Triggers Analysis
- Track downloaded successfully
- Check settings (is analysis enabled?)
- Check resources (battery, CPU, RAM)
Step 2: Audio Processing
- Decode audio file to raw waveform
- Apply DSP algorithms
- Extract musical features (BPM, key, loudness, etc.)
- Generate Visualisation data
Step 3: Data Storage
- Save analysis metadata to track
- Save heavy Visualisation (spectrogram) to separate file
- Update track record with analysis data
Step 4: Ready for Use
- Analysis data available in Sonic Analysis page
- Sonic Twins can find matching tracks
- Playback uses loudness data for leveling
Smart Resource Management
Battery Protection (Mobile Devices):
- Analysis only runs when device is charging
- Prevents battery drain during portable use
- Queued tracks analyzed when power connected
CPU Protection:
- Monitors CPU usage during analysis
- Switches to lighter processing if CPU > 90%
- Prevents system slowdown
Memory Protection:
- Monitors available RAM
- Adjusts processing if RAM < 200MB free
- Prevents out-of-memory crashes
Integration with Other Features
Playback & Audio
Loudness Leveling:
- Uses
sonic_analysis_data.loudness.integrated(LUFS) - Automatically adjusts volume between tracks
- Consistent listening experience across different recordings
Audio Effects:
- Analysis data used for EQ presets
- Dynamic range information for compression settings
Downloads System
Automatic Analysis:
- Triggers based on Run Mode setting
- Runs after download completes
- Stores results with downloaded track
Storage Management:
- Analysis metadata: stored with track (~1-5 KB)
- Visualisation data: stored separately (~100KB-1MB)
- Spectrogram SVG: static image file (~10-50 KB)
DJ Mode
Future Integration:
- Planned DJ modes (Gemini, Freeze) will use sonic analysis
- More intelligent track selection based on actual musical content
- Better matching than server-side similarity alone
Sonic Twins
Cross-Track Discovery:
- Scans all downloaded tracks
- Finds musically compatible tracks
- Uses BPM and key matching algorithms
- Powered by Camelot Wheel system
Error Handling & Reliability
What Happens When Things Go Wrong
Corrupt or Invalid Files:
- Analysis gracefully fails
- Error message shown to user
- Track remains usable without analysis data
Network Issues:
- Analysis runs locally on device
- No network required for analysis
- Network only needed for plugin updates
Resource Constraints:
- Smart analysis detects low battery, high CPU, low RAM
- Adjusts processing or skips analysis
- No crashes or hangs
Self-Healing Features
- Automatic Retry: Planned feature to retry failed analysis
- Graceful Degradation: Track works fine even if analysis fails
- Background Processing: Doesn't block user experience
- Progress Tracking: Real-time progress indicator during analysis
Technical Specifications
| Specification | Value |
|---|---|
| Analysis Tiers | 3 (Base, Extended, Full) |
| BPM Detection Range | 60-200 BPM |
| Musical Keys | 12 pitch classes × 2 modes (Major/Minor) = 24 keys |
| Camelot Notation | 1A-12A (Minor), 1B-12B (Major) |
| LUFS Measurement | Integrated (K-weighted) |
| Spectrogram Modes | 4 (Waveform, Linear, Log, Bars) |
| Chromagram Views | 4 (Enhanced, Peaks, Summary, Raw) |
| Sonic Twins Results | Top 10 matches |
| Minimum Twin Score | 50/100 |
| Twin Scoring | BPM 60%, Key 40% |
| Platform Targets | 6 (Spotify, Apple, YouTube, Tidal, Amazon, Broadcast) |
| Execution Modes | 4 (Automatic, Native, Web Worker, Main Thread) |
| Run Modes | 4 (Always, Auto, After Download, Disabled) |
| Battery Protection | Yes (mobile only) |
| i18n Support | 19 languages |
Sonic Analysis Data Structure
What Gets Analyzed
Core Musical Data:
- BPM and tempo confidence
- Musical key (pitch class + mode)
- Time signature
- Beat positions and timestamps
- Audio segments with features
Extended Technical Data:
- Spectral centroid, rolloff, flux, zero crossing rate
- Energy metrics (overall, dynamic range, crest factor)
- Rhythm metrics (swing, syncopation, groove)
- Waveform data
- Transients and mood analysis
Advanced Data (Full tier):
- Harmony (chord progressions, complexity)
- Spatial (stereo width, phase correlation)
- Quality (bit depth, sample rate, artifacts)
- Visualisation data (spectrogram, chromagram)
- Audio fingerprints and embeddings
Sonic Twins Comparison
| Feature | BPM Matching | Key Matching | Overall Score |
|---|---|---|---|
| Weight | 60% | 40% | Weighted Average |
| Perfect Match | ≤1% difference | Exact Camelot match | 100/100 |
| Good Match | ≤3% difference | Adjacent keys | 80-90/100 |
| Acceptable | ≤6% difference | Related keys | 50-70/100 |
| No Match | >6% difference | Unrelated keys | <50/100 |
Use Cases
Music Production & Mastering
Scenario: You're mastering tracks for release
- Check LUFS against streaming platform targets
- Verify dynamic range meets standards
- Identify clipping and DC offset issues
- Ensure platform readiness scores are high
Playlist Creation
Scenario: Building the perfect playlist
- Use Sonic Twins to find compatible tracks
- Match BPM for consistent energy
- Use key compatibility for smooth transitions
- Create harmonically-flowing sets
DJ Preparation
Scenario: Planning a DJ set
- Analyse your library for BPM and key data
- Use Camelot notation for harmonic mixing
- Find compatible transition tracks
- Identify energy boost options (+2, +7)
Audio Quality Assessment
Scenario: Evaluating your music collection
- Identify highly compressed tracks
- Find tracks with excellent dynamic range
- Check for artifacts and quality issues
- Compare remasters and different versions
Related Documentation
- Downloads System - Analysis triggers and storage
- Settings System - Sonic analysis configuration
- DJ Mode - Future integration with sonic analysis
- Audio Engine - Loudness leveling using analysis data
- Player & Queue - Track changes and analysis data