HEARD - Audio Analysis Tool

HEARD Documentation

SELECT GUIDE:

Getting Started

HEARD is a professional audio analysis tool for musicians, engineers, and producers. Real-time frequency visualization, spectrum analysis, and pitch tracking in your browser.

Click 'START' and allow microphone access
Choose analysis mode: Spec, RTA, Tuner, or Combined
Adjust settings via ⋯ SETTINGS button

Analysis Modes

Spectrogram

Frequency vs time waterfall (20Hz-20kHz, logarithmic). Touch/click to freeze and measure. Enable PITCH button for orange tracking overlay.

RTA (Real-Time Analyzer)

31-band 1/3-octave analysis. Use A-weighting for noise, C-weighting for peaks, Flat for unweighted. Peak hold with adjustable decay.

Tuner

Chromatic tuner (60Hz-2000Hz) using YIN algorithm. Shows note, octave, cents (±1 cent accuracy). Green when in tune.

Combined View

Split-screen RTA + Spectrogram for mixing/mastering workflows.

FFT Settings

FFT	Resolution	Best For
1024	~47 Hz / 21 ms	Live performance
2048	~23 Hz / 43 ms	Balanced (default)
4096	~12 Hz / 85 ms	Detailed analysis
8192	~6 Hz / 170 ms	High precision
16384	~3 Hz / 341 ms	Maximum detail

Controls & Overlays

Spectrogram: GRID • LEGEND • TELEM • COORD • PITCH

RTA: A/C/FLAT weighting • PEAK hold • FREEZE

Window Functions: HANN (default) • HAMMING • BLACKMAN • RECT

Keyboard Shortcuts

Key	Action
1-4	Switch screens
Space	Freeze/Unfreeze
?	Open this guide
Esc	Close modal

Tips & Best Practices

Tuning: Use Tuner mode, play single notes, position mic close, wait for green indicator.

Room Acoustics: RTA mode with A-weighting, peak hold on, measure multiple positions.

Mixing: Combined view, FFT 4096/8192, monitor RMS, enable pitch tracking.

Live: FFT 1024/2048 for speed, enable GRID, use RTA for feedback identification.

Troubleshooting

No audio: Check mic permissions, ensure mic connected, refresh page

Poor performance: Lower FFT to 2048/1024, close other tabs, use Chrome

Tuner not detecting: Play louder, single notes only, check Tuner mode active

Pitch tracking invisible: Click PITCH button, sing/play sustained note

Interface Themes

Dark Mode (Default)

Professional dark interface, reduced eye strain, classic studio aesthetic. Orange accent (#FF9500).

Light Mode

Clean bright interface, better for well-lit environments, high visibility. Same orange accent.

Switch: ⋯ SETTINGS → Choose theme. Saved automatically via localStorage.

Spectrogram Color Ramps (12 Options)

Scientific (Research-Grade)

VIRIDIS ⭐ - Perceptually uniform, colorblind-friendly. Best for publication/analysis.

PLASMA - High contrast purple→pink→orange→yellow. Excellent detail visibility.

INFERNO - Black→purple→red→orange→yellow. Maximum dynamic range.

MAGMA - Black→purple→pink→orange→white. Volcanic aesthetic.

Musical & Creative

THERMAL (Default) - Classic heat map. Familiar, easy to read.

TURBO - Vibrant rainbow. Visible from distance, eye-catching.

SPECTRUM - Full rainbow. Maximum color range.

FIRE - Black→red→orange→yellow→white. Intense flame.

Specialized

OCEAN - Dark blue→cyan→light blue. Cool, calming.

CLASSIC - Blue→green→yellow→red. Traditional spectrum analyzer.

MONO - Black→orange→white. Matches UI accent.

GRAYSCALE - Pure black→white. Print-friendly, no color distraction.

Color Scheme Recommendations

Use Case	Best Scheme
Mixing & Mastering	THERMAL or VIRIDIS
Live Performance	TURBO or SPECTRUM
Room Acoustics	VIRIDIS or GRAYSCALE
Teaching/Presentation	PLASMA or INFERNO
Recording Sessions	OCEAN or CLASSIC
Publication/Research	VIRIDIS (industry standard)
Print Documents	GRAYSCALE

Preference Persistence

All settings auto-save to localStorage:

✓ Theme (Dark/Light)
✓ Color Scheme
✓ FFT Size
✓ Window Function

Reset: Browser DevTools (F12) → Console → localStorage.clear() → Refresh

Accessibility Notes

Colorblind-friendly: VIRIDIS, GRAYSCALE, INFERNO

Print-safe: GRAYSCALE, VIRIDIS

High contrast: PLASMA, INFERNO, FIRE

Eye strain reduction: Dark mode + OCEAN scheme

Quick Share Options

1. File Share (Easiest - 5 min)

Upload HEARD_FINAL.html to Dropbox/Google Drive, share link. Colleagues download and open in browser.

Pros: Zero setup, works immediately
Cons: Manual downloads, no auto-updates

2. GitHub Pages (Free - 15 min) ⭐

Recommended for most users.

Create GitHub account (free)
New repository → Name it "heard-analyzer" → Public
Upload HEARD_FINAL.html, rename to "index.html"
Settings → Pages → Deploy from branch "main"
URL: https://YOUR-USERNAME.github.io/heard-analyzer/

Pros: Free forever, automatic HTTPS, professional URL, easy updates
Cons: Requires GitHub account

3. Netlify Drop (Fastest - 2 min)

Go to app.netlify.com/drop, drag HEARD_FINAL.html, get instant URL.

Pros: Instant deployment, custom domain support
Cons: Random URL unless custom domain

4. Local Network Server (Studio - 10 min)

Terminal:

python3 -m http.server 8080

Share: http://YOUR-COMPUTER-IP:8080/HEARD_FINAL.html

Pros: No internet needed, zero latency, instant updates
Cons: Computer must stay on, local network only

System Requirements

Browser: Chrome 90+, Firefox 88+, Safari 14+, Edge 90+
Audio: Microphone or audio input device
Recommended: Desktop/laptop for full features
Mobile: Works with reduced features

Security & Permissions

Microphone Access

Browser requests permission on first use. HTTPS sites remember permission, HTTP sites ask each session.

HTTPS Requirement

✓ GitHub Pages - Automatic HTTPS
✓ Netlify - Automatic HTTPS
⚠ Local server - HTTP only (permissions reset)

Updating After Deployment

GitHub Pages

Edit HEARD_FINAL.html locally
Go to GitHub repository
Click index.html → Edit (pencil icon)
Paste new code → Commit changes
Wait 1-2 minutes for update

Local Server

Edit HEARD_FINAL.html
Save file
Tell users to refresh (Cmd+R / Ctrl+R)

Sharing Best Practices

✓ Send deployment separately from password (if added)
✓ Include quick start instructions
✓ Mention browser compatibility
✓ Test on target devices first
✓ Provide support contact info

Custom Branding (Optional)

Change title: Line 11: <title>HEARD</title>

Change colors: Line 80: --accent-primary: #FF9500;

Add logo: Insert <img> in intro screen

Architecture Overview

HEARD is a single-file HTML application using Web Audio API for real-time audio analysis. All processing happens client-side in the browser.

Core Components

Web Audio API - AudioContext, AnalyserNode for FFT processing
Canvas System - Spectrogram, RTA, Tuner, pitch overlay rendering
Analysis Modes - 4 screens with independent rendering pipelines
State Management - localStorage for persistence, sessionStorage for runtime

Screen Management

currentScreen variable controls active view:

0 = Spectrogram
1 = RTA (Real-Time Analyzer)
2 = Tuner
3 = Combined (RTA + Spectrogram)

Frequency Mapping Formulas

Spectrogram Y-Position to Frequency

Logarithmic scale from 20Hz (bottom) to 20kHz (top):

logPos = (h - y) / h
frequency = 20 * Math.pow(1000, logPos)

Pitch Overlay Frequency to Y-Position

Inverse of spectrogram mapping (critical for alignment):

logPos = Math.log10(freq / 20) / 3
y = h - (logPos * h)

Verification: Built-in verification calculates frequency from Y to ensure accuracy. Check console for "✓ Pitch" logs.

YIN Pitch Detection Algorithm

Industry-standard autocorrelation-based pitch detector (De Cheveigné & Kawahara, 2002).

Five-Step Process

Difference Function - Measures self-similarity at different lags
Cumulative Mean Normalization - Prevents false low-frequency detections
Absolute Threshold - Finds first minimum below 0.15
Parabolic Interpolation - Refines period estimate using 3 points
Frequency Calculation - Converts period to Hz

Parameters

Range: 60Hz - 2000Hz (musical instrument range)
Confidence: >85% required for detection
Threshold: 0.15 for normalized difference function
Buffer: Equal to FFT size for accuracy

Color Scheme System

Palette-based color interpolation for spectrogram rendering.

Structure

Each scheme = array of RGB triplets [R, G, B]

thermal: [[20,0,40], [40,0,80], [0,0,120], ...]

Interpolation Algorithm

getColorForIntensity(intensity) function:

Map intensity (0-1) to palette position
Find adjacent color stops
Linear interpolate RGB values
Return rgb(r, g, b) string

Adding New Schemes

Add to colorSchemes object (line ~2550):

myscheme: [[0,0,0], [128,0,128], [255,255,0]]

Then add button in settings HTML with data-color-scheme="myscheme"

Canvas Rendering Performance

Double-Buffering Technique

Spectrograms use off-screen buffer for smooth horizontal scrolling:

Draw visible canvas to buffer canvas
Draw buffer to visible canvas shifted left 3px
Fill exposed 3px strip on right with new data
Repeat at animation frame rate (~60fps)

DPR Scaling

Device Pixel Ratio handling for Retina displays:

canvas.width = offsetWidth * dpr
canvas.height = offsetHeight * dpr
ctx.scale(dpr, dpr)

Display coordinates: Use offsetWidth/offsetHeight
Canvas coordinates: Scaled by DPR automatically

Modification Guides

Change Pitch Detection Range

Edit detectPitchForOverlay() function (line ~4900):

const minFreq = 60; // Change to your min
const maxFreq = 2000; // Change to your max

Adjust Visual Style

Pitch overlay styling in drawPitchOverlay() (line ~5060):

ctx.strokeStyle = 'rgba(255, 149, 0, alpha)'; // Color
ctx.lineWidth = 2; // Width in pixels
ctx.shadowBlur = 3; // Glow amount

Change Trail Length

Pitch history buffer (line ~2640):

pitchHistory = []; // Stores 300 frames

Adjust maxHistoryFrames = 300 or modify fade calculation:

alpha = baseAlpha * Math.pow(0.98, age); // Faster fade = 0.95

Add New Overlays

Create canvas: <canvas id="myOverlay">
Get context in init: myOverlayG = myOverlayCanvas.getContext('2d')
Add to render loop: Call your drawMyOverlay() function
Handle DPR scaling in resize handler

Performance Optimization

Target Metrics

Frame Rate: 60fps (16.67ms per frame)
Latency: <50ms input to display
CPU Usage: <40% on modern hardware
Memory: <200MB typical

Optimization Techniques Used

RequestAnimationFrame - Synced to display refresh
Double-buffering - Smooth scrolling without full redraws
Typed Arrays - Uint8Array for FFT data (faster than standard arrays)
Canvas caching - Off-screen buffers reduce redundant draws
Conditional rendering - Only draw visible screens

If Performance Issues

Lower FFT size (2048 → 1024)
Reduce smoothing iterations
Disable pitch tracking overlay
Turn off grid/legend overlays

Testing & Debugging

Console Logging

Pitch tracking logs verification:

✓ Pitch: 440.0Hz → logPos: 0.4922 → Y: 493.7px → Verify: 440.0Hz

Common Debugging Points

Microphone not working: Check navigator.mediaDevices.getUserMedia promise
Canvas blank: Verify DPR scaling, check offsetWidth/Height > 0
Pitch misaligned: Check console logs, verify formula matches spectrogram
Performance lag: Check FPS counter in telemetry, reduce FFT size

Browser DevTools

Useful console commands:

localStorage.getItem('heardTheme') // Check saved theme
fftSize // Current FFT size
currentScreen // Active screen (0-3)
pitchHistory.length // Pitch tracking buffer

File Structure

Code Organization (Line Numbers)

75-170: CSS Variables & Themes
172-920: Main Interface Styling
989-1170: Help Modal & Settings Panel
2070-2300: HTML Structure (Intro, Settings, App)
2900-3050: Global Variables & Configuration
3050-3500: Audio Initialization & Web Audio Setup
3500-4200: Canvas Drawing Functions (Spec, RTA, Tuner)
4200-4600: Event Handlers & UI Controls
4600-5100: Pitch Detection & Overlay Rendering
5100-5800: Animation Loop & Utility Functions

Key Functions Reference

Function	Purpose	Line
init()	Initialize Web Audio API	~3200
drawSpec()	Render spectrogram	~3300
drawRTA()	Render RTA bars	~3700
drawTuner()	Render chromatic tuner	~4000
detectPitchForOverlay()	YIN pitch detection	~4900
updatePitchOverlay()	Update pitch history	~4950
drawPitchOverlay()	Render pitch line	~5060
getColorForIntensity()	Color interpolation	~2550

Browser Compatibility Notes

Required APIs

Web Audio API (AudioContext, AnalyserNode)
Canvas 2D (getContext('2d'))
getUserMedia (microphone access)
localStorage (preferences)
ES6+ (arrow functions, const/let, template strings)

Browser-Specific Notes

Safari: Requires user gesture before AudioContext creation (handled)

Firefox: May need about:config media.navigator.permission.disabled = false for easier testing

Mobile: Reduced features on small screens, orientation lock on iPhone

Future Enhancement Ideas

WAV/MP3 export of analysis session
Screenshot/video capture of visualizations
Custom frequency range selection
Multi-channel analysis (stereo L/R)
Preset save/load system
MIDI output from pitch detection
Harmonic analysis overlay
Room mode identification
Waterfall 3D spectrogram mode
Plugin system for custom analyzers

Contributing & Customization

This is a single-file application - all code is in HEARD_FINAL_POLISHED.html

Best Practices

Test changes in multiple browsers
Maintain backward compatibility with localStorage
Keep performance metrics (60fps target)
Document new features in help modal
Use consistent naming conventions
Add console logging for debugging

Code Style

Use camelCase for variables/functions
Use const for constants, let for variables
Comment complex algorithms thoroughly
Organize with section headers (═══ style)
Keep functions focused and under 50 lines when possible

HEARD - Professional Audio Analysis Tool • Version 2.0

Press ESC or click × to close