🚀 QUICKSTART - 05_11_GRAPH_SYSTEM¶

¿Quieres empezar YA? Esta es tu guía.

⚡ 5 MINUTOS PARA ENTENDER TODO¶

¿Qué es esto?¶

El Graph System es el "director de orquesta" que coordina el procesamiento de audio en AudioLab:

[Input] → [Gain] → [Filter] → [Reverb] → [Output]

Pero puede ser mucho más complejo:

              ┌─ [Reverb] ─┐
[Input] → Split            Mix → [Limiter] → [Output]
              └─ [Delay] ──┘
                    ↑_______|  (feedback)

El Graph System: - ✅ Conecta nodos (gain, filtros, efectos) - ✅ Valida que las conexiones sean correctas - ✅ Ordena el procesamiento automáticamente - ✅ Optimiza para multi-core - ✅ Compensa latencias - ✅ Visualiza el flujo de señal

📂 ¿DÓNDE ESTÁ QUÉ?¶

05_11_GRAPH_SYSTEM/
│
├── README.md                    ← Empieza aquí (resumen completo)
├── PLAN_DE_DESARROLLO.md        ← Plan detallado 76 semanas
├── STRUCTURE.md                 ← Mapa de carpetas
├── QUICKSTART.md                ← Estás aquí!
│
├── 05_11_00_graph_core/         ← TAREA 1: Empezar por aquí
│   ├── include/                 ← Headers: GraphNode.h, AudioGraph.h
│   ├── src/                     ← Implementación C++
│   ├── tests/                   ← Tests unitarios
│   └── README.md                ← Guía de esta tarea
│
├── 05_11_01_topology_validation/ ← TAREA 2: Después del core
├── 05_11_02_topological_sorting/ ← TAREA 3: Orden de procesamiento
├── ... (9 tareas más)
│
└── 05_11_documentation/         ← Docs finales

🎯 ¿POR DÓNDE EMPIEZO?¶

Opción 1: SOY DESARROLLADOR - Quiero implementar¶

# 1. Lee el contexto
cat README.md                                    # 5 min

# 2. Lee la primera tarea
cat 05_11_00_graph_core/README.md                # 3 min

# 3. Mira el plan detallado de esa tarea
cat PLAN_DE_DESARROLLO.md | grep "TAREA 1" -A 50  # 5 min

# 4. Crea tu primer header
cd 05_11_00_graph_core/include
# Crea GraphNode.h siguiendo el plan

# 5. Implementa
cd ../src
# Crea GraphNode.cpp

# 6. Testea
cd ../tests
# Crea test_graph_node.cpp

Opción 2: SOY ARQUITECTO - Quiero entender¶

# 1. Arquitectura general
cat README.md

# 2. Plan completo
cat PLAN_DE_DESARROLLO.md | less

# 3. Estructura de carpetas
cat STRUCTURE.md

# 4. Revisa cada subsistema
for dir in 05_11_*/; do
    echo "=== $dir ==="
    cat "$dir/README.md" 2>/dev/null || echo "No README yet"
done

Opción 3: SOY PROJECT MANAGER - Quiero planificar¶

# 1. Timeline completo
cat PLAN_DE_DESARROLLO.md | grep "TAREA"

# 2. Métricas de éxito
cat PLAN_DE_DESARROLLO.md | grep "MÉTRICAS"

# 3. Dependencias
cat STRUCTURE.md | grep "DEPENDENCIAS"

# 4. Recursos necesarios
cat PLAN_DE_DESARROLLO.md | grep "EQUIPO"

🏃 INICIO RÁPIDO: Primera Implementación¶

Goal: Grafo simple que funcione (Input→Gain→Output)¶

Tiempo estimado: 2-3 días

Día 1: Estructuras básicas¶

// include/GraphNode.h
class GraphNode {
public:
    virtual void process(float* input, float* output, int numSamples) = 0;
};

// include/AudioGraph.h
class AudioGraph {
    std::vector<GraphNode*> nodes;
public:
    void addNode(GraphNode* node);
    void process(float* input, float* output, int numSamples);
};

Día 2: Implementación + Tests¶

// src/AudioGraph.cpp
void AudioGraph::process(float* input, float* output, int numSamples) {
    float* buffer = input;
    for (auto* node : nodes) {
        node->process(buffer, buffer, numSamples);
    }
    std::copy(buffer, buffer + numSamples, output);
}

// tests/test_simple_chain.cpp
TEST_CASE("Simple gain chain") {
    AudioGraph graph;
    GainNode gain1(2.0f);
    GainNode gain2(0.5f);

    graph.addNode(&gain1);
    graph.addNode(&gain2);

    float input[512] = {1.0f, ...};
    float output[512];

    graph.process(input, output, 512);

    REQUIRE(output[0] == Approx(1.0f));  // 1.0 * 2.0 * 0.5 = 1.0
}

Día 3: Ejemplo funcional¶

// examples/simple_chain.cpp
int main() {
    AudioGraph graph;

    InputNode input;
    GainNode gain(2.0f);
    OutputNode output;

    graph.addNode(&input);
    graph.addNode(&gain);
    graph.addNode(&output);

    // Process 10 seconds
    for (int i = 0; i < 10 * 48000 / 512; ++i) {
        graph.process();
    }

    return 0;
}

¡Listo! Tienes un grafo DSP funcional básico.

📚 DOCUMENTOS CLAVE POR ROL¶

Para Implementadores¶

PLAN_DE_DESARROLLO.md - Sección "Core Implementation" de cada tarea
05_11_XX_*/README.md - Guía específica de cada componente
Código conceptual en el plan (copiar/adaptar)

Para Testers¶

PLAN_DE_DESARROLLO.md - Sección "Testing Framework" de cada tarea
Coverage targets (>90% típico)
Test types: unit, integration, performance, audio quality

Para Documentadores¶

PLAN_DE_DESARROLLO.md - Sección "Documentación" de cada tarea
05_11_documentation/ - Estructura de docs finales
API reference format

Para Arquitectos¶

README.md - Visión general
PLAN_DE_DESARROLLO.md - Sección "Marco Teórico-Práctico"
STRUCTURE.md - Dependencias entre componentes

🎓 CONCEPTOS CLAVE EN 2 MINUTOS¶

1. Node (Nodo)¶

¿Qué es? Una unidad de procesamiento Ejemplo: Gain, Filter, Reverb Código: class GraphNode { void process(...); }

2. Edge (Conexión)¶

¿Qué es? Cable entre nodos Ejemplo: Output de Gain → Input de Filter Código: graph.connect(gainNode, 0, filterNode, 0)

3. Topological Sort¶

¿Qué es? Orden correcto de procesamiento Por qué: Si Filter va antes de Gain, suena mal! Algoritmo: Kahn's algorithm (O(V+E))

4. Latency Compensation¶

¿Qué es? Alinear señales con diferentes delays Por qué: Reverb añade 50ms, dry debe retrasarse 50ms Solución: Auto-inserción de delays

5. Parallel Processing¶

¿Qué es? Procesar ramas independientes en threads separados Por qué: Usar todos los cores del CPU Resultado: 3-4x speedup típico

⚠️ TRAMPAS COMUNES¶

❌ NO HAGAS ESTO¶

// ❌ Crear nodos en audio thread
void process() {
    auto node = new GainNode();  // MALLOC EN AUDIO THREAD!
}

// ❌ Modificar grafo durante procesamiento
void process() {
    graph.addNode(newNode);  // RACE CONDITION!
}

// ❌ Ordenar manualmente
nodes = {input, filter, gain, output};  // ORDEN INCORRECTO!

✅ HAZ ESTO¶

// ✅ Pre-allocar todo
void prepare() {
    node = new GainNode();  // En prepare, no en process
}

// ✅ Usar shadow graph para cambios
void reconfigure() {
    shadowGraph = activeGraph.clone();
    shadowGraph.addNode(newNode);
    swapGraphs();  // Atomic
}

// ✅ Usar topological sort
auto sorted = sorter.sort(graph);  // Orden automático

🚦 CHECKLIST DE INICIO¶

Setup Inicial¶

Leído README.md completo
Leído PLAN_DE_DESARROLLO.md (al menos resumen)
Entendida la estructura de carpetas
Environment setup (compiler, CMake, Catch2)

Antes de Implementar Tarea X¶

Leído README.md de la tarea
Leído sección del plan detallado
Entendidas las dependencias
Revisado código conceptual
Claro sobre entregables

Durante Implementación¶

Antes de Marcar Como Completa¶

🆘 ¿PROBLEMAS?¶

No entiendo X concepto¶

→ Lee PLAN_DE_DESARROLLO.md sección "Marco Teórico-Práctico" → Busca el algoritmo específico (ej: "Kahn's Algorithm") → Referencias al final del plan

No sé por dónde empezar¶

→ Empieza por Tarea 1: 05_11_00_graph_core → Lee su README.md → Sigue el orden: Types.h → Port.h → Node → Edge → Graph

Los tests no pasan¶

→ Verifica coverage: ¿qué no está testeado? → Compara con código conceptual del plan → Revisa test examples en el plan

Performance no cumple targets¶

→ Revisa benchmarks en el plan → Aplica optimizaciones sugeridas → Considera usar 05_11_10_graph_optimization

📞 RECURSOS¶

Documentos¶

README.md - Resumen del subsistema
PLAN_DE_DESARROLLO.md - Plan completo
STRUCTURE.md - Estructura de carpetas

Referencias Externas¶

JUCE AudioProcessorGraph
Max/MSP gen~
CLRS Algorithms (Cap. 22: Graphs)
Real-Time Rendering (Cap. 15: Optimization)

Herramientas¶

Catch2 (testing)
CMake (build)
Valgrind (memory leaks)
Perf (profiling)

🎉 SIGUIENTE PASO¶

# Si eres nuevo:
cat README.md

# Si vas a implementar:
cd 05_11_00_graph_core
cat README.md
# Empieza a codear!

# Si vas a planificar:
cat PLAN_DE_DESARROLLO.md | less

TL;DR: 1. Lee README.md (5 min) 2. Lee PLAN_DE_DESARROLLO.md resumen (10 min) 3. Empieza con 05_11_00_graph_core 4. Sigue el orden de tareas 5. Tests >90% coverage 6. ¡Disfruta construyendo el mejor graph system ever! 🚀

Creado: 2025-10-14 Versión: 1.0.0 Autor: AudioLab Development Team