darkgraycat/bleeder

Purpose and Entry Points

Bleeder is a Go-based live-coding/audio-generation system: it reads “bleed” source files, parses a music-oriented DSL, builds an intermediate representation, renders audio, and can play WAV output. The executable entry point is main.go; CLI construction and command context live in cmd/cmd.go, cmd/cfg.go, and cmd/ctx.go.

Example DSL inputs are stored under bleeds/, including bleeds/aelin.practice.toml and bleeds/just_playing.toml.

CLI and Execution Context

The command layer owns process-level configuration and dispatch into the core engine. cmd/cfg.go and root config.toml establish configuration boundaries, while cmd/ctx.go appears to carry shared execution context between CLI operations and runtime services.

The top-level control path is expected to be:

main.go → cmd/ command setup → core Bleeder orchestration → parse/render/play stages.

Core Bleeder Orchestration

internal/core/bleeder.go is the principal application coordinator. It works with bleed inputs and their context through internal/core/bleed.go and internal/core/bleedctx.go. This is the main boundary between user-authored source/configuration and the compiler-like audio pipeline.

The core package is where parsing results, runtime options, and downstream renderer/player dependencies should be assembled rather than embedded in CLI commands.

DSL Parsing and IR Boundary

The repository has two parser implementations, internal/core/parser.go and internal/core/parser2.go, suggesting an evolving syntax model. Both feed the canonical intermediate representation in internal/ir/ir.go.

This IR is the key architectural contract: parsers translate bleed syntax into structured musical/audio instructions; renderers should consume IR rather than depend on source syntax. DSL intent and planned behavior are documented in docs/aelin/dsl-design.md, docs/aelin/parser-design.md, and docs/aelin/syntax-model-v2.md.

Audio Synthesis and Rendering

Audio-domain primitives are concentrated in internal/audio/notes.go, internal/audio/waves.go, and internal/audio/wav.go. These likely provide note/frequency handling, waveform generation, and WAV encoding.

Rendering is abstracted by internal/renderer/renderer.go, with WAV-specific implementation in internal/renderer/wav_renderer.go. The rendering boundary converts IR/audio instructions into a material audio artifact, keeping file-format concerns separate from parsing and orchestration.

Playback and Runtime Output

Playback is separated from rendering in internal/player/player.go and internal/player/wav_player.go. This permits a generated WAV artifact to be consumed by a player implementation independently of how it was synthesized.

The system therefore has a clear output chain: IR → renderer → WAV/audio output → player. Audio-device behavior, buffering, and streaming concerns are architecturally relevant and discussed in docs/aelin/streaming-architecture.md and docs/aelin/buffer-drain-solution.md.

Live-Coding Integration

The extensions/bleeder-vscode/ package provides a VS Code integration, principally through extensions/bleeder-vscode/extension.js. It is an external editor-facing control surface rather than part of the Go runtime pipeline.

Supporting design documents, especially docs/aelin/live-coding-architecture.md and LIVE_CODING_PLAN.md, indicate that rapid source update, parse/rebuild, and audio-output lifecycle management are central future/runtime concerns.