songbird-state

Pure data layer for the Songbird DAW. Defines the project data model, entity types, channel-aligned state slices, and persistence. This crate has no business logic, no I/O beyond persistence, and no engine dependencies.

Architecture

songbird-state/src/
├── ids.rs              Strongly-typed entity IDs (TrackId, ClipId, etc.)
├── map.rs              Map<K, V> — ordered collection with dirty tracking
├── entities/           Domain entity structs (atoms)
├── slices/             Channel-aligned slice structs (molecules)
├── state_manager.rs    StateManager — root state container (organism)
├── store/              StateStore — change tracking, undo/redo, listeners
└── persistence/        File I/O: bird text, session autosave, git history

Layer Hierarchy

StateManager           ← single root, composes all slices
  └── 10 Slices        ← one per sync engine channel
       └── Entities    ← individual domain types
            └── IDs    ← strongly-typed keys

Entities

Domain types with Serialize + Deserialize. No business logic beyond constructors and accessors.

Entity	File	Description
`Track`	`entities/track.rs`	Audio/MIDI track metadata
`Clip`	`entities/clip.rs`	Audio or MIDI clip content
`MixerState`	`entities/mixer.rs`	Per-track mix state (gain, pan, mute, solo)
`PluginInstance`	`entities/plugin.rs`	Plugin instance with saved parameter state
`AutomationLane`	`entities/automation.rs`	Parameter automation breakpoints
`Section`	`entities/section.rs`	Arrangement section
`SongMetadata`	`entities/song.rs`	BPM, key, time signature
`ProjectMetadata`	`entities/project.rs`	Project name, ID, sample rate
`LoopState`	`entities/transport.rs`	Loop region and enable state
`MetronomeState`	`entities/transport.rs`	Click track settings
`ArmState`	`entities/recording.rs`	Per-track record arm and input routing
`Marker` / `Region`	`entities/marker.rs`	Timeline markers, regions, tempo/key markers
`ChatStore`	`entities/chat.rs`	AI chat history and model config
`GenerationStore`	`entities/generation.rs`	AI generation job history
`UserSettings`	`entities/settings.rs`	Global user preferences

Slices

Channel-aligned structs that group related entities. Each slice maps 1:1 to a sync engine channel and a persistence file.

Slice	Channel	Persistence file	Contents
`SongSlice`	`track.`, `section.`	`{name}.bird`	tracks, sections, tempo/key markers
`ClipSlice`	`track.*`	`{name}.bird`	clips
`AutomationSlice`	`track.*`	`{name}.bird`	automation lanes
`ProjectSlice`	`project.*`	`daw.state.json`	metadata, markers, regions, engine config
`TransportSlice`	`transport.*`	`daw.state.json`	loop state, metronome
`RecordingSlice`	`recording.*`	`daw.state.json`	per-track arm state
`MixerSlice`	`mixer.*`	`daw.mixer.json`	per-track mix, sends, returns, master bus
`PluginSlice`	`plugin.*`	`daw.plugins.json`	plugin instances
`AiSlice`	`ai.*`	`daw.ai.json`	chat, generation
`SettingsSlice`	`settings.*`	`settings.json`	user preferences (global)

StateManager

The root state container. One StateManager per open project.

pub struct StateManager {
    pub song:       SongSlice,
    pub clip:       ClipSlice,
    pub automation: AutomationSlice,
    pub project:    ProjectSlice,
    pub transport:  TransportSlice,
    pub recording:  RecordingSlice,
    pub mixer:      MixerSlice,
    pub plugin:     PluginSlice,
    pub ai:         AiSlice,
    pub settings:   SettingsSlice,
}

Key property: because each field is a separate struct, Rust allows simultaneous &mut borrows of different slices — e.g., a mixer command can mutate state.mixer while a transport command reads state.transport.

StateStore

Wraps StateManager with:

Undo/redo — snapshots before each mutation
Change listeners — notify subscribers on mutation
Dirty tracking — which slices changed since last persist
Git persistence — commit state to git-backed project history

Persistence

Module	Purpose
`persistence/bird_io.rs`	`.bird` text format read/write
`persistence/session.rs`	Crash-recovery autosave + recent project list
`persistence/project_history.rs`	Git-based commit history

Crate	Relationship
`songbird-sync`	Imports entities/slices for command dispatch. Also hosts `generation_state` and `bridge_layer` runtime services.
`songbird-files`	Filesystem services (samples, presets, loops, templates). No dependency on state.
`songbird-types`	Shared low-level types (`TimeStretchMode`, ARA traits). State depends on this.

Architecture

Core (zero-dep foundations)

Engine & DSP

Data & Sync

Machine Learning

Integration

Orchestration

Application Shells

songbird-state

songbird-state

Architecture

Layer Hierarchy

Entities

Slices

StateManager

StateStore

Persistence

​songbird-state

​Architecture

​Layer Hierarchy

​Entities

​Slices

​StateManager

​StateStore

​Persistence

​Related Crates

songbird-state

Architecture

Layer Hierarchy

Entities

Slices

StateManager

StateStore

Persistence

Related Crates