# Effect Depth Analysis Results

## Overview
The `seq_compiler` tool now includes a `--analyze` flag to identify performance bottlenecks by analyzing how many effects are stacked (running simultaneously) at each moment in the demo.

## Usage

```bash
# Analyze effect stacking depth
./build/seq_compiler assets/demo.seq --analyze

# Generate analysis with visual Gantt chart
./build/seq_compiler assets/demo.seq --analyze --gantt-html=timeline_analysis.html
```

## Current Demo Analysis (demo.seq)

### Summary
- **Timeline duration**: 36s (65 beats @ 120 BPM)
- **Total effects**: 57
- **Max concurrent effects**: 11 at t=8.8s ⚠️
- **Bottleneck periods**: 28 time periods with >5 effects

### Effect Depth Distribution

| Depth | Time % | Severity |
|-------|--------|----------|
| 1-2   | 28.3%  | Light    |
| 3-4   | 26.1%  | Moderate |
| 5-6   | 15.9%  | Heavy    |
| 7-11  | 29.6%  | Critical ⚠️ |

**Key Finding**: Nearly 30% of the demo has 7+ effects running simultaneously, which may cause frame rate drops on lower-end hardware.

### Identified Bottlenecks

**Most Critical Sections** (10+ concurrent effects):

1. **t=4.3s** (10 effects): FlashCubeEffect, FadeEffect, ParticleSprayEffect, ParticlesEffect, GaussianBlurEffect, HeptagonEffect, ThemeModulationEffect, ChromaAberrationEffect, SolarizeEffect, FlashEffect
2. **t=8.6s** (10 effects): FlashCubeEffect, ThemeModulationEffect, ParticleSprayEffect, ParticlesEffect, Hybrid3DEffect, GaussianBlurEffect, ChromaAberrationEffect, HeptagonEffect, FlashEffect (×2)
3. **t=8.8s** (11 effects) - **Peak bottleneck**

**Heavy Sections** (7-9 concurrent effects):
- t=4.9s: 9 effects
- t=6.7s: 9 effects
- t=7.3s: 7 effects
- t=7.9s: 8 effects
- t=9.1s: 9 effects
- ... and 18 more peaks

### Recommendations

**Immediate Actions**:
1. **Reduce overlap at t=8.8s**: The 11-effect peak is excessive. Consider:
   - Staggering effect start/end times by 0.1-0.2s
   - Removing redundant effects (e.g., duplicate FlashEffect instances)
   - Combining similar effects (e.g., multiple GaussianBlur passes)

2. **Optimize sequence at 8b-12b** (4-6 seconds):
   - This section has sustained high effect counts (6-10 effects)
   - Consider moving some post-processing effects to later sequences
   - Test frame rate on target hardware during this section

3. **Profile specific effects**:
   - GaussianBlurEffect appears frequently (28 instances)
   - Hybrid3DEffect runs for long durations (20s total)
   - ChromaAberrationEffect appears in most bottleneck periods

**Optimization Strategies**:
- Use priority layering to ensure critical effects render at higher priority
- Consider effect LOD (Level of Detail) system for lower-end hardware
- Combine multiple post-process passes into single shaders where possible
- Profile GPU time per effect to identify true bottlenecks (not just count)

### Effect Frequency Analysis

**Most Used Effects** (estimated from analysis output):
1. GaussianBlurEffect: ~10 instances
2. HeptagonEffect: ~9 instances
3. ThemeModulationEffect: ~7 instances
4. ChromaAberrationEffect: ~6 instances
5. FlashCubeEffect: ~6 instances
6. ParticleSprayEffect: ~5 instances
7. ParticlesEffect: ~5 instances
8. SolarizeEffect: ~4 instances
9. Hybrid3DEffect: ~3 instances
10. FadeEffect: ~2 instances

**Insight**: GaussianBlur and Heptagon effects are the most heavily used - optimizing these will have the biggest impact on overall performance.

## Technical Details

### Analysis Method
- Samples timeline at 10 Hz (every 0.1s)
- Counts overlapping effect time ranges at each sample
- Generates histogram of effect depth distribution
- Identifies peaks (>5 effects) with at least 0.5s separation

### Limitations
- Does not measure actual GPU/CPU time per effect (only counts)
- Assumes all effects have equal performance cost (not true in practice)
- Does not account for effect complexity (e.g., particle count, shader passes)

### Future Improvements
- Add GPU profiling integration (Tracy, RenderDoc)
- Weight effects by estimated performance cost
- Suggest specific optimizations per bottleneck
- Generate timeline heatmap visualization
- Compare multiple .seq files (before/after optimization)

---

**Generated**: February 8, 2026
**Analysis Tool**: seq_compiler v1.1 (--analyze flag)
**Target**: assets/demo.seq