Graph Framework

Graph-based processing infrastructure for real-time audio and video. Provides directed-graph topology, automatic scheduling, and zero-allocation execution. Originally developed in libbahn (music tracker), generalized into libmediacore for all media consumers.

Location

src/libs/libmediacore/mediacore/graph/
  Graph.hpp / .cpp
  GraphNode.hpp / .cpp
  Connection.hpp / .cpp
  Buffer.hpp / .cpp
  BufferPool.hpp / .cpp
  ProcessorCharacter.hpp / .cpp
  Schedule.hpp / .cpp
  ScheduleFactory.hpp / .cpp
  Job.hpp / .cpp

Architecture

The framework has three layers:

+---------------------------------------------------------------------+
|                              GRAPH LAYER                            |
|  Graph -> GraphNode -> Connection                                   |
|  - DFS-based cycle detection                                        |
|  - Topology change tracking                                         |
|  - Spatial queries (lasso selection)                                |
+---------------------------------------------------------------------+
                                |
                                v (on topology change)
+---------------------------------------------------------------------+
|                          COMPILATION LAYER                           |
|  ScheduleFactory -> Schedule -> Job[]                               |
|  - BFS traversal for job ordering                                   |
|  - Buffer allocation via "Dowry" pattern                            |
|  - Zero-copy buffer inheritance                                     |
+---------------------------------------------------------------------+
                                |
                                v (during playback)
+---------------------------------------------------------------------+
|                          EXECUTION LAYER                             |
|  Engine.process() -> Schedule.process() -> Job.execute()            |
|  - Single contiguous memory block                                   |
|  - 32-byte aligned buffers (SIMD-ready)                             |
|  - No allocation during processing                                  |
+---------------------------------------------------------------------+

Graph layer

Graph

Container for nodes and connections. Tracks topology changes and provides queries.

GraphNode

Base class for all processing nodes. Each node declares its input/output character via ProcessorCharacter.

ProcessorCharacter

Declares a node's role in the graph.

Derived convenience methods:

Connection

Directed edge between two nodes. The graph layer validates that connections don't create cycles using DFS traversal.

Compilation layer

ScheduleFactory

Compiles a Graph into an executable Schedule by:

1. BFS traversal from source nodes to determine processing order
2. Buffer allocation using the "Dowry" pattern -- each node receives pre-allocated buffer slots
3. Zero-copy buffer inheritance where possible (output buffer of one node reused as input of the next)

Schedule

An ordered list of Job entries backed by a single contiguous memory block.

Job

A single processing step: a node reference plus its buffer assignment.

Execution layer

Memory layout

All buffers are allocated as a single contiguous block with 32-byte alignment:

static const size_t BUFFER_ALIGNMENT_BYTES{32};

32-byte alignment enables AVX/AVX2 SIMD operations. Misaligned access causes 2-10x slowdown on x86.

Zero-allocation guarantee

During processing, no memory allocation occurs:

• All buffers are pre-allocated at compilation time
• Job list is a flat array
• Node processing writes directly into pre-assigned buffer slots

This is critical for real-time audio where allocation can cause glitches.

Buffer

SIMD-aligned buffer with external memory ownership (the Schedule owns the memory, Buffer provides a typed view).

Extension: libbahn

The music tracker (libbahn) extends this framework with audio-specific concepts:

Applications that need the graph engine but not the tracker (e.g., singularity's jingle system) can use AudioNode directly without importing tracker-specific code.

Usage example

// Build a simple graph
Graph graph;
auto* source = new OscNode(440.0);  // 440 Hz sine
auto* gain = new GainNode(0.5);     // 50% volume
auto* output = new OutputNode();

graph.addNode(source);
graph.addNode(gain);
graph.addNode(output);
graph.connect(source, gain);
graph.connect(gain, output);

// Compile to schedule
ScheduleFactory factory;
Schedule schedule = factory.compile(graph);

// Process one buffer
schedule.process();

See Also

• Media Architecture - Design rationale
• Device Management - Device enumeration and caching
• Video Streaming - Vision system and streaming