# 🚀 START HERE — Spatial-BEATs Documentation Guide

**Welcome!** You have access to comprehensive analysis of the Spatial-BEATs codebase. This guide will direct you to exactly what you need.

---

## ⚡ Quick Pick Your Task

### "I have 5 minutes"
→ Read: [`SPATIAL_FRAMEWORKS_QUICK_REFERENCE.md`](SPATIAL_FRAMEWORKS_QUICK_REFERENCE.md)

### "I have 15 minutes"
→ Read: [`README_DOCUMENTATION_INDEX.md`](README_DOCUMENTATION_INDEX.md) then [`ANALYSIS_COMPLETION_SUMMARY.md`](ANALYSIS_COMPLETION_SUMMARY.md)

### "I have 30 minutes"
→ Choose one:
- **New to codebase?** Read: Part 1 of [`SPATIAL_AUDIO_FRAMEWORKS_ANALYSIS.md`](SPATIAL_AUDIO_FRAMEWORKS_ANALYSIS.md)
- **Debugging DOA gap?** Read: [`doa_train_valid_gap_analysis.md`](doa_train_valid_gap_analysis.md) Executive Summary
- **Planning experiments?** Read: [`0427_v11_series.md`](0427_v11_series.md) Section 1-2

### "I have 1-2 hours"
→ Full reading path for your role:
- **Researcher**: QUICK_REF → 0427_v11_series.md → ANALYSIS Part 2-3
- **Contributor**: QUICK_REF → ANALYSIS Part 1-2 → Pick component → read code
- **Investigator**: DOA_GAP Executive → Part 6 → Part 8 → Appendix

---

## 📚 The Five Documents

### 1. **README_DOCUMENTATION_INDEX.md** 
🏠 **Navigation hub** — Where to find what
- Use case lookup (choose your problem)
- Code component quick reference
- Reading order for different roles
- Cross-reference guide

**👉 Read this first if**: You're not sure where to start

---

### 2. **SPATIAL_FRAMEWORKS_QUICK_REFERENCE.md**
⚡ **Practitioner's card** — Fast lookup
- Framework table (4 frameworks, 1 page)
- Route A/B/C comparison
- Version series highlights
- Code locations by component
- Loss weight patterns
- When to use each configuration

**👉 Read this for**: Quick answers, practitioner reference

---

### 3. **SPATIAL_AUDIO_FRAMEWORKS_ANALYSIS.md**
📖 **Deep technical reference** — Architecture bible
- Part 1: Four spatial frameworks (Spatial-AST, DCASE SELD, EINV2, DETR)
- Part 2: Routes A/B/C with full specifications
- Part 3: Version evolution (v7→v11)
- Part 4-10: Implementation, configs, metrics, future work
- Appendix: Code reference table

**👉 Read this for**: Deep understanding, architecture details, code paths

---

### 4. **doa_train_valid_gap_analysis.md**
🔍 **Diagnostic & fix guide** — Root cause analysis
- Executive Summary: 6 critical mechanisms
- Part 1: Data pipeline analysis
- Part 2: Loss computation asymmetry
- Part 3: Training configuration (v9/v10)
- Part 4: Validation metrics
- **Part 6: Root causes ranked by severity**
- **Part 7: Diagnostic checklist**
- **Part 8: Recommended fixes (prioritized)**
- Appendix: Code reference with exact line numbers

**👉 Read this for**: Debugging train/val gaps, understanding root causes

---

### 5. **ANALYSIS_COMPLETION_SUMMARY.md**
📋 **Executive overview** — What was found
- Deliverables summary (5 docs, 1,883 lines)
- Key findings (frameworks, routes, v11 series)
- Next steps (immediate vs experimental)
- How to use documents
- Verification checklist

**👉 Read this for**: Overview, decision-making, what comes next

---

## 🎯 Choose Your Path

### Path 1: "I want to understand the architecture (60 min)"
1. SPATIAL_FRAMEWORKS_QUICK_REFERENCE.md (5 min)
2. SPATIAL_AUDIO_FRAMEWORKS_ANALYSIS.md Part 1-2 (25 min)
3. Pick a component from Part 6 Appendix, find in code (20 min)
4. spatial_beats_ov123_frame_routes.md if curious (10 min)

**Outcome**: Can navigate codebase, understand paradigms, modify code confidently

---

### Path 2: "I need to debug a train/val gap (30 min)"
1. doa_train_valid_gap_analysis.md Executive Summary (2 min)
2. Part 6: Check which mechanisms apply to your situation (5 min)
3. Part 7: Diagnostics—check your logs (10 min)
4. Part 8: Pick a fix priority (5 min)
5. Appendix: Get code locations (2 min)
6. SPATIAL_FRAMEWORKS_QUICK_REFERENCE.md if you need to modify (optional)

**Outcome**: Root cause identified, fix strategy chosen, code locations ready

---

### Path 3: "I want to run an experiment (v11 series) (45 min)"
1. SPATIAL_FRAMEWORKS_QUICK_REFERENCE.md (5 min)
2. 0427_v11_series.md Section 1-2 (15 min)
3. SPATIAL_AUDIO_FRAMEWORKS_ANALYSIS.md Part 3 (15 min)
4. 0427_v11_series.md Part 4 (verification method) (5 min)
5. Copy shell script from QUICK_REF (5 min)

**Outcome**: Experiment ready to launch, understanding of success metrics

---

### Path 4: "I'm new, I want to understand everything (2 hours)"
1. SPATIAL_FRAMEWORKS_QUICK_REFERENCE.md (10 min)
2. SPATIAL_AUDIO_FRAMEWORKS_ANALYSIS.md Part 1-3 (40 min)
3. spatial_beats_ov123_frame_routes.md (25 min)
4. spatial_beats_training_overview.md (20 min)
5. Pick component, trace through code with Part 6 references (20 min)
6. doa_train_valid_gap_analysis.md Part 6 for context (5 min)

**Outcome**: Comprehensive understanding of system, ready to contribute

---

## 🔑 Key Findings at a Glance

### 4 Spatial Frameworks in Codebase
- **Spatial-AST**: Task tokens (pre-trunk)
- **DCASE SELD**: Per-class activity+DOA
- **EINV2**: Learnable track queries
- **DETR**: Per-frame K-slot allocation

### 3 Parallel Routes (A/B/C)
- **Route A**: Per-frame K-slot, per-step Hungarian
- **Route B**: Learnable queries, clip-level Hungarian (PRODUCTION v9)
- **Route C**: Per-class vectors (PROTOTYPE, v11c test)

### DOA Train/Val Gap Root Causes
1. ⚠️⚠️⚠️ **ZERO spatial augmentation (rotations)** — 40-60% of variance
2. ⚠️⚠️ **SpecAugment train-only** — 10-20% variance
3. ⚠️⚠️ **v10 freezes direction head** — 30-40% on multi-source
4. ⚠️ **Regression sensitivity** — 5-15% variance
5. ⚠️ **Detached prediction asymmetry** — 2-5% variance

### v11 Experiments (Parallel Runs)
- **v11a**: DOA demixer → ov2 angles ↓ 5pp+
- **v11b**: LocalSpatial pre-pool → test IV necessity
- **v11c**: ACCDOA paradigm → ov3 binding ↓ 5pp+
- **v11d**: Post-hoc calibration → ov1 ranking ↑ 5pp+

---

## 📞 FAQ

**Q: Where do I find the direction head loss?**  
A: `SPATIAL_AUDIO_FRAMEWORKS_ANALYSIS.md` Appendix → search "direction loss" → `spatial_loss.py:1562-1565`

**Q: What's the difference between routes?**  
A: Compare table in `SPATIAL_FRAMEWORKS_QUICK_REFERENCE.md` or detailed Part 2 of `SPATIAL_AUDIO_FRAMEWORKS_ANALYSIS.md`

**Q: Should I implement fix #1, #2, or #3?**  
A: Read `doa_train_valid_gap_analysis.md` Part 6, pick based on your gap size and risk tolerance.

**Q: How do I run v11a?**  
A: Shell script in `SPATIAL_FRAMEWORKS_QUICK_REFERENCE.md` v11 section + spec in `0427_v11_series.md` Section 2.2

**Q: I'm stuck on a component. Where's the code?**  
A: `SPATIAL_AUDIO_FRAMEWORKS_ANALYSIS.md` Part 6 has complete reference table with file:line for every component.

---

## 🎁 You Now Have

✅ **Navigation guide** for all documents
✅ **Quick reference card** with all the essentials
✅ **Architecture bible** with code paths
✅ **Diagnostic guide** for train/val gaps
✅ **Experimental specifications** for v11 series
✅ **Comprehensive metadata** (1,883 lines, 77KB)
✅ **All findings tied to exact code locations**

---

## 🚀 Next Steps

1. **Choose your path above** based on how much time you have
2. **Follow the reading order** in that path
3. **Use cross-references** when you need more detail
4. **Check Appendices** for exact code locations
5. **Reference Part 6/Part 8** when implementing

---

## 📊 Document Overview

| Document | Size | Time | Purpose |
|----------|------|------|---------|
| README_DOCUMENTATION_INDEX | 12KB | 5-10m | Navigation hub |
| SPATIAL_FRAMEWORKS_QUICK_REFERENCE | 7KB | 5-10m | Quick lookup |
| SPATIAL_AUDIO_FRAMEWORKS_ANALYSIS | 28KB | 30-45m | Deep reference |
| doa_train_valid_gap_analysis | 19KB | 20-30m | Diagnostics |
| ANALYSIS_COMPLETION_SUMMARY | 11KB | 10m | Executive summary |
| **TOTAL** | **77KB** | **2-4 hours** | **Complete set** |

---

**Status**: ✅ Complete and ready for use
**Created**: 2026-04-27
**Next update**: After v11 experiments

👉 **Pick your path above and start reading!**