Spatial Trajectory Tracker — User Guide
Frame‑based stereo field analysis: tracks panning position, stereo width, and energy distribution over time with comprehensive visualization.
What this does
This script implements spatial trajectory tracking — a comprehensive analysis tool for stereo audio that tracks panning position, stereo width, and channel energy distribution over time. The script performs frame‑based analysis on stereo input, calculating: (1) Pan position: ‑1 (full left) to +1 (full right). (2) Stereo width: 0 (mono) to 1 (full stereo). (3) Channel energy: RMS energy per channel. (4) Temporal smoothing: Adjustable moving‑average filtering. (5) Silence gating: Automatic detection and exclusion of silent frames. Key features: (1) 4 Built‑in Presets: Fast overview, detailed analysis, ultra‑smooth, transient‑sensitive. (2) Multi‑panel visualization: Panning trajectory, polar stereo field, waveform display. (3) Statistical analysis: Mean, standard deviation, range, bias classification. (4) Data table output: Comprehensive Praat Table with all computed metrics.
Key Features:
- Frame‑based stereo analysis — Tracks panning over time
- Polar field visualization — Shows spatial distribution in 2D
- 4 Analysis presets — Optimized for different audio types
- Adjustable smoothing — Control temporal resolution
- Silence‑adaptive processing — Gates out silent sections
- Statistical classification — Auto‑classifies bias and movement
Technical Implementation: (1) Frame‑based processing: Divides audio into overlapping frames (configurable length/hop). (2) Pan calculation: pan = (R‑L)/(R+L) based on RMS energy. (3) Width estimation: width = 1 − |R‑L|/(R+L). (4) Smoothing: Moving‑average filter across frames. (5) Silence gating: Excludes frames below threshold. (6) Visualization: Three‑panel display: panning trajectory over time, polar stereo field (pan→angle, energy→radius), and waveform. (7) Data output: Praat Table with time, pan_raw, pan_smooth, energy_L, energy_R, width columns.
Quick start
- In Praat, select exactly one Stereo Sound object (2 channels).
- Run script… →
spatial_trajectory_tracker.praat. - Choose a Preset (overrides parameters) or "Manual" to use sliders.
- Adjust Frame_length_s (analysis resolution, default 0.02s = 20ms).
- Set Hop_size_s (frame overlap, default 0.01s = 10ms).
- Choose Silence_gate_dB (threshold for excluding silent frames).
- Set Smoothing_frames (moving‑average window, higher = smoother).
- Select visualization options: Show_waveform, Show_polar_plot.
- Click OK — analysis performed, table created: "SpatialAnalysis_originalname_presetname".
Spatial Analysis Theory
Panning Calculation Fundamentals
🎛️ Pan Position Definition
Psychoacoustic considerations: The simple energy‑based pan calculation approximates perceived position for most mixed audio. However, actual psychoacoustic pan perception involves interaural level differences (ILD), interaural time differences (ITD), and spectral cues. For detailed analysis of binaural recordings or complex spatialization, more sophisticated models would be needed.
Stereo Width Estimation
Energy‑Based Width Metric
Width vs. Pan Relationship
Wide Center (width=1.0, pan=0.0): • Equal energy both channels • Sounds appear across entire stereo field • Common for: Reverbs, pads, stereo keyboards
Narrow Center (width=0.0, pan=0.0): • Mono signal (identical both channels) • Sounds appear as point source at center • Common for: Lead vocals, kick, snare, bass
Wide Panned (width=1.0, pan≠0.0): • Impossible with simple energy model • Would require decorrelated signals with pan bias
Narrow Panned (width=0.0, pan≠0.0): • All energy in one channel • Sounds appear as point source at side • Common for: Hard‑panned guitars, percussion
Frame‑Based Processing
⏱️ Temporal Analysis Parameters
Temporal resolution trade‑off: The choice of frame length involves a fundamental trade‑off between time resolution and frequency (or in this case, spatial) resolution. Short frames can track rapid panning changes but produce noisy estimates. Long frames produce stable estimates but may average across multiple panning positions. The hop size controls how densely the trajectory is sampled — smaller hop sizes produce smoother visualizations but require more computation.
Smoothing Algorithm
Moving‑Average Smoothing
Implementation: For each frame i, average pan values from i‑K to i+K where K = floor(Smoothing_frames/2).
Mathematical: pan_smooth[i] = (1/(2K+1)) Σ_{j=i‑K}^{i+K} pan_raw[j]
Edge handling: Uses available frames (startF = max(1, i‑K), endF = min(N, i+K)).
Effect: Reduces high‑frequency variance while preserving overall trends.
Silence Gating
Threshold calculation: gateThreshold = 10^(Silence_gate_dB/20) (convert dB to linear).
Logic: If totalRMS = sqrt(E_L + E_R) ≤ gateThreshold, frame considered silent.
Silent frame handling: Uses last valid pan value (carry‑forward).
Purpose: Prevents noise in silent sections from affecting statistics and visualization.
Statistical Calculations
Mean pan: μ = (1/N_valid) Σ pan[i] (only valid/ungated frames).
Variance: σ² = (1/N_valid) Σ (pan[i]−μ)².
Standard deviation: σ = √σ².
Range: maxPanR − maxPanL (extreme values).
Valid frames: Frames above silence threshold.
Visualization Methods
📊 Three‑Panel Display System
Panel 1: Panning Trajectory • X‑axis: Time (0 to duration) • Y‑axis: Pan position (‑1 to +1) • Raw data: Light blue, thin line • Smoothed data: Dark blue, thick line • Mean line: Red dotted line • Background: Left zone (pink), right zone (blue)
Panel 2: Polar Stereo Field • Coordinate system: Pan → angle, Energy → radius • Angle mapping: ‑1 (left) = 180°, 0 (center) = 90°, +1 (right) = 0° • Radius mapping: radius = min(1, totalRMS × 10) • Color gradient: Blue (start) → Red (end) shows temporal evolution • Background: Semicircle representing stereo field
Panel 3: Waveform Display • Standard stereo waveform • Gray color for reference • Provides temporal context for spatial analysis
Statistics Panel • Mean pan, standard deviation, range • Frame count, valid percentage • Bias classification with color‑coded text
Parameters & Presets
Common Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
| Preset | optionmenu | Manual | 4 built‑in presets or manual control |
| Frame_length_s | positive | 0.02 | Analysis window length in seconds |
| Hop_size_s | positive | 0.01 | Time between successive analysis frames |
| Silence_gate_dB | real | -60.0 | Threshold for excluding silent frames (dB) |
| Smoothing_frames | integer | 10 | Moving‑average window size in frames |
| Draw_visualization | boolean | 1 (yes) | Enable graphical display |
| Show_waveform | boolean | 1 (yes) | Include waveform panel |
| Show_polar_plot | boolean | 1 (yes) | Include polar stereo field panel |
Built‑in Presets
| Preset | Frame Length | Hop Size | Smoothing | Silence Gate | Character |
|---|---|---|---|---|---|
| Fast Overview | 50 ms | 25 ms | 5 frames | -50 dB | Quick general analysis |
| Detailed Analysis | 10 ms | 5 ms | 15 frames | -65 dB | Precise automation tracking |
| Ultra Smooth | 30 ms | 15 ms | 30 frames | -55 dB | Trend‑focused visualization |
| Transient Sensitive | 5 ms | 2 ms | 3 frames | -70 dB | Rapid change detection |
Preset Design Philosophy
🎛️ Preset Characteristics Explained
Fast Overview: • Longer frames (50 ms): Stable estimates, less variance • Moderate hop (25 ms): 50% overlap for smoothness • Light smoothing (5 frames): Preserves general shape • Higher silence gate (-50 dB): Focuses on audible content • Use: Quick assessment of overall spatial characteristics
Detailed Analysis: • Short frames (10 ms): High temporal resolution • Small hop (5 ms): 50% overlap for dense sampling • Moderate smoothing (15 frames): Reduces noise while keeping detail • Low silence gate (-65 dB): Includes quiet sections • Use: Precise tracking of panning automation, subtle changes
Ultra Smooth: • Medium frames (30 ms): Balance of resolution and stability • Moderate hop (15 ms): 50% overlap • Heavy smoothing (30 frames): Very smooth curves • Moderate silence gate (-55 dB): Excludes very quiet noise • Use: Visualizing overall trends, reducing visual clutter
Transient Sensitive: • Very short frames (5 ms): Maximum temporal resolution • Tiny hop (2 ms): 60% overlap for ultra‑smooth trajectory • Minimal smoothing (3 frames): Preserves transients • Very low silence gate (-70 dB): Captures all activity • Use: Analyzing rapid spatial changes, percussion, effects
Parameter Relationships
Applications
Mix Analysis & Reverse Engineering
Use case: Understanding professional mixing techniques
Technique: Use Detailed Analysis preset
Tip: Analyze individual tracks to see panning automation, then full mix to see spatial balance
Advanced: Compare multiple mixes of same song to see different engineers' spatial approaches
Automation Extraction & Editing
Use case: Extracting panning automation from audio
Technique: Use Transient Sensitive preset for precise tracking
Tip: Export Table data, convert to automation curves in DAW
Advanced: Smooth extracted data, apply to other sounds for matching spatial movement
Stereo Width Monitoring
Use case: Ensuring consistent stereo width in productions
Technique: Use Fast Overview preset on full mixes
Tip: Monitor width column in Table — consistent values indicate good stereo imaging
Advanced: Set width thresholds, flag sections that become too mono or too wide
Educational Tool
Use case: Teaching stereo mixing concepts
Technique: Use all visualization panels
Tip: Show how different panning positions and automation moves appear in visualizations
Advanced: Create before/after examples of spatial processing (stereo wideners, panning effects)
Quality Control & Troubleshooting
Use case: Detecting spatial problems in mixes
Technique: Look for anomalies in trajectory
Tip: Sudden jumps may indicate phase issues. Consistent bias may indicate monitoring/balance problems.
Advanced: Compare left/right energy plots to detect imbalance
Practical Workflow Examples
🎵 Analyzing Classic Stereo Mix
Goal: Understand spatial techniques in classic recording
Settings:
- Preset: Detailed Analysis
- Frame: 15 ms, Hop: 7.5 ms
- Smoothing: 20 frames
- Silence gate: -60 dB
- All visualizations enabled
Analysis: Track individual instruments to see panning choices, observe how width changes between sections
🎚️ Extracting Pan Automation
Goal: Extract panning curve from sound effect for reuse
Settings:
- Preset: Transient Sensitive
- Frame: 5 ms, Hop: 2 ms
- Smoothing: 5 frames
- Silence gate: -70 dB
- Visualization: Trajectory only
Result: Precise pan curve that can be applied to other sounds
🔍 Diagnosing Phase Issues
Goal: Identify phase cancellation in stereo mix
Settings:
- Preset: Fast Overview
- Frame: 40 ms, Hop: 20 ms
- Smoothing: 10 frames
- Silence gate: -50 dB
- Visualization: Trajectory + Energy plots
Analysis: Look for sections where width suddenly drops while energy remains — indicates phase cancellation
Troubleshooting Common Issues
Cause: Frame length too short, or smoothing too low
Solution: Increase frame length, increase smoothing frames, or use Ultra Smooth preset
Cause: Frame length too long, or smoothing too high
Solution: Decrease frame length, decrease smoothing, or use Transient Sensitive preset
Cause: Low energy normalization, or mainly mono content
Solution: Check energy values in Table — if low, audio may be quiet. Radius scaling factor (×10) may need adjustment.
Cause: Silence gate too high, or audio very quiet
Solution: Lower Silence_gate_dB, or normalize audio before analysis
Cause: Hard‑panned audio, or one channel silent
Solution: This is correct behavior for hard‑panned material. Check if intentional.
Processing Pipeline
🔄 Spatial Trajectory Analysis Pipeline
START: User Selects Stereo Sound
│
▼
INPUT VALIDATION
│ • Check exactly one Sound selected
│ • Verify number of channels = 2 (stereo)
│ • Exit with error if not stereo
│
▼
FORM PROCESSING
│ • Load user parameters from form
│ • Apply preset overrides if selected
│ • Preset mapping:
│ Manual → "Manual"
│ Fast Overview → "FastOverview"
│ Detailed Analysis → "Detailed"
│ Ultra Smooth → "UltraSmooth"
│ Transient Sensitive → "Transient"
│
▼
SOUND PROPERTIES
│ • Get duration, sampling frequency
│ • Write InfoLine header with parameters
│
▼
CHANNEL EXTRACTION
│ • Extract channel 1 → ch1ID
│ • Extract channel 2 → ch2ID
│ • Maintain separate objects for analysis
│
▼
FRAME CALCULATION
│ • numFrames = floor((dur − frame_length_s) / hop_size_s)
│ • Validate: require numFrames ≥ 2
│ • Write frame count to InfoLine
│
▼
DATA TABLE CREATION
│ • Create Table: "pan_data" with numFrames rows
│ • Columns: time, pan_raw, pan_smooth, energy_L, energy_R, width
│
▼
THRESHOLD CALCULATION
│ • gateThreshold = 10^(silence_gate_dB / 20)
│ • epsilon = 1e-7 (prevent division by zero)
│
▼
ANALYSIS LOOP (frame by frame)
│ For i = 1 to numFrames:
│ │
│ ├── TIME CALCULATION
│ │ • tStart = (i−1) × hop_size_s
│ │ • tEnd = tStart + frame_length_s
│ │ • tMid = (tStart + tEnd) / 2 (frame center)
│ │
│ ├── ENERGY MEASUREMENT
│ │ • selectObject: ch1ID
│ │ • rmsL = Get root‑mean‑square: tStart, tEnd
│ │ • selectObject: ch2ID
│ │ • rmsR = Get root‑mean‑square: tStart, tEnd
│ │ • energyL = rmsL², energyR = rmsR²
│ │ • totalRMS = sqrt(energyL + energyR)
│ │
│ ├── STEREO WIDTH CALCULATION
│ │ • if energyL + energyR > epsilon:
│ │ width = 1 − abs(energyR − energyL) / (energyL + energyR + epsilon)
│ │ • else: width = 0
│ │
│ ├── SILENCE GATING
│ │ • if totalRMS > gateThreshold:
│ │ # Valid frame (above silence threshold)
│ │ calcPan = (energyR − energyL) / (energyR + energyL + epsilon)
│ │ • Clamp: if calcPan > 1: calcPan = 1
│ │ if calcPan < −1: calcPan = −1
│ │ • Update statistics accumulators
│ │ • lastValidPan = calcPan
│ │ • else:
│ │ # Silent frame (use last valid)
│ │ calcPan = lastValidPan
│ │
│ └── TABLE STORAGE
│ • Set numeric value: i, "time", tMid
│ • Set numeric value: i, "pan_raw", calcPan
│ • Set numeric value: i, "pan_smooth", calcPan (initial)
│ • Set numeric value: i, "energy_L", energyL
│ • Set numeric value: i, "energy_R", energyR
│ • Set numeric value: i, "width", width
│
▼
CLEANUP CHANNEL OBJECTS
│ • removeObject: ch1ID, ch2ID
│ • Only Table remains with raw data
│
▼
SMOOTHING PROCESS
│ • if smoothing_frames > 1:
│ │ halfWin = floor(smoothing_frames / 2)
│ │ For i = 1 to numFrames:
│ │ │ startF = max(1, i − halfWin)
│ │ │ endF = min(numFrames, i + halfWin)
│ │ │ sum = 0, count = 0
│ │ │ For j = startF to endF:
│ │ │ sum = sum + Get value: j, "pan_raw"
│ │ │ count = count + 1
│ │ │ avg = sum / count
│ │ │ Set numeric value: i, "pan_smooth", avg
│
▼
STATISTICAL CALCULATIONS
│ • if validFrames > 0:
│ │ meanPan = sumPan / validFrames
│ │ variancePan = (sumPanSq / validFrames) − (meanPan²)
│ │ if variancePan < 0: variancePan = 0
│ │ stdPan = sqrt(variancePan)
│ │ panRange = maxPanR − maxPanL
│ • else:
│ │ meanPan = 0, stdPan = 0, panRange = 0
│
▼
CLASSIFICATION
│ • if meanPan < −0.1: biasDesc$ = "left‑biased"
│ • elsif meanPan > 0.1: biasDesc$ = "right‑biased"
│ • else: biasDesc$ = "centered"
│
│ • if stdPan < 0.1: moveDesc$ = "static"
│ • elsif stdPan < 0.3: moveDesc$ = "moderate movement"
│ • else: moveDesc$ = "dynamic"
│
▼
VISUALIZATION PIPELINE (if enabled)
│
├── LAYOUT CALCULATION
│ • Based on show_waveform and show_polar_plot
│ • 3 panels, 2 panels, or 1 panel layout
│ • Calculate viewport coordinates
│
├── PANEL 1: PANNING TRAJECTORY
│ • Axes: 0‑dur, −1.1‑1.1
│ • Background: Left zone (pink), right zone (blue)
│ • Grid lines at 0, ±0.5
│ • Draw raw data (light blue, thin)
│ • Draw smoothed data (dark blue, thick)
│ • Draw mean line (red dotted)
│ • Labels: R, C, L on left
│
├── PANEL 2: POLAR STEREO FIELD (if enabled)
│ • Axes: −1.3‑1.3, −0.3‑1.3
│ • Draw semicircle outline
│ • Draw guide lines (0°, 45°, 90°, 135°, 180°)
│ • For each frame:
│ │ angle = (90 − pan×90) × π/180
│ │ radius = min(1, sqrt(energyL+energyR)×10)
│ │ x = cos(angle)×radius, y = sin(angle)×radius
│ │ color: blue→red gradient based on time
│ │ Paint small rectangle at (x,y)
│ • Statistics panel (right side):
│ │ Mean, std, range, frame count, valid %
│ │ Bias classification with color‑coded text
│
└── PANEL 3: WAVEFORM (if enabled)
• Standard stereo waveform display
• Gray color for reference
• Time axis labeled
│
▼
FINAL DATA PREPARATION
│ • Rename Table: "SpatialAnalysis_" + originalName$ + "_" + presetName$
│ • Select both Sound and Table objects
│ • Write completion message to InfoLine
│
END: Analysis complete, Table ready for inspection
Frame‑Based Analysis Algorithm
Polar Plot Coordinate Transformation
📐 Pan → Angle, Energy → Radius Mapping
Visual interpretation: The polar plot shows the stereo field as a semicircle. Points near the top center represent centered sounds. Points to the left/right represent panned sounds. Distance from center represents loudness (energy). Color shows temporal progression. Dense clusters indicate stable positions, spreading indicates movement.
Statistical Classification System
Left‑Biased (meanPan < −0.1): • Average position leans left • Common in: Some jazz recordings, live recordings with audience left • Color: Red text (0.8, 0.3, 0.3)
Centered (|meanPan| ≤ 0.1): • Balanced stereo field • Common in: Modern pop, electronic, carefully mixed material • Color: Green text (0.3, 0.6, 0.3)
Right‑Biased (meanPan > 0.1): • Average position leans right • Common in: Some classical recordings, live recordings with audience right • Color: Blue text (0.3, 0.3, 0.8)
Movement Classification:
Static (stdPan < 0.1): • Little panning movement • Common in: Minimalist mixes, mono‑heavy material
Moderate Movement (0.1 ≤ stdPan < 0.3): • Some panning changes • Common in: Typical pop/rock mixes
Dynamic (stdPan ≥ 0.3): • Significant panning movement • Common in: Experimental music, sound design, automation‑heavy mixes
Performance Characteristics
Mathematical Deep Dive
Energy‑Based Panning Analysis
Frame‑Based RMS Statistics
RMS calculation properties: