armin/xtc
1
0
Fork 0
forked from hanez/xtc
Code Pull requests Activity

Some code semantics refactoring.

Browse source
This commit is contained in:
Johannes Findeisen 2026-10-27 01:37:21 +01:00
commit 0f04e056b2
42 changed files with 3374 additions and 1357 deletions
Download patch file Download diff file Expand all files Collapse all files

259
docs/ROADMAP.md
View file

@ -116,4 +116,263 @@ RECOVERY.md. Native graphs remain session-only, with unsupported saves preservin
files. No stable binary plugin ABI, external host, system package, autosave or
physical-device/endurance qualification is claimed.
## Phase 10 — Engine Correctness and Reliability
**Goal:** Verify that the existing implementation behaves correctly under realistic workloads before adding more features.
### Tasks
- Audit graph compilation, topological ordering, port compatibility, and cycle detection.
- Test graph replacement while audio is running, including safe reclamation of old processing graphs.
- Verify that audio-thread operations are bounded and non-blocking.
- Test repeated initialization, start/stop cycles, device failures, shutdown, and partial initialization.
- Run AddressSanitizer, UndefinedBehaviorSanitizer, leak checks, and static analysis where available.
- Add regression tests for every bug discovered.
- Document known limitations and thread ownership for shared resources.
### Acceptance criteria
- Reproducible tests cover engine lifecycle, graph changes, error handling, and DSP output.
- No known critical real-time safety defects remain.
- Resource ownership and cleanup behavior are documented.
## Phase 11 — Complete Minimal Music-Making Workflow
**Goal:** Ensure a user can create, save, reopen, and play a small musical project without manually editing project files.
### Tasks
- Verify project creation, track creation, clip arrangement, routing, and transport as one integrated workflow.
- Ensure play, pause, stop, seek, and return-to-start behavior are consistent.
- Save, close, reopen, and continue editing projects.
- Provide useful defaults and actionable error messages.
- Keep the sequencer as the default workspace, with the modular graph available when needed.
- Test that GUI state and engine state remain synchronized.
### Acceptance criteria
- A user can create and reopen a small project and reproduce the same arrangement and routing.
- Common operations do not require manual project-file edits.
- Transport and GUI state remain consistent during normal playback and error conditions.
## Phase 12 — Audio Quality and Transport Correctness
**Goal:** Make timing and audio output predictable and musically reliable.
### Tasks
- Define precise behavior for tempo and meter changes.
- Verify conversion between musical positions and sample positions without accumulated timing drift.
- Test clips and events that cross processing-block boundaries.
- Prevent clicks at clip boundaries and during playback start/stop where appropriate.
- Implement gain ramps and parameter smoothing where abrupt changes could create artifacts.
- Test silence, clipping, denormal values, channel layouts, and unusual supported buffer sizes.
- Document latency reporting and identify whether latency compensation is required by the current architecture.
- Add deterministic tests for sample-accurate event scheduling where supported.
### Acceptance criteria
- Automated tests verify timing conversions and expected sample output.
- Tests cover events and clips at block boundaries and tempo changes.
- Listening tests cover transitions, start/stop behavior, and representative projects.
- Known limitations involving latency and synchronization are documented.
## Phase 13 — Recording and Recovery
**Goal:** Protect recorded material and handle recording failures predictably.
### Tasks
- Test long recordings and recording-buffer saturation.
- Handle disk-full conditions, write errors, interrupted recording, and unavailable destinations.
- Keep file I/O outside the real-time audio callback.
- Define and implement recovery or clear reporting for incomplete recordings.
- Make recording destinations and supported file formats explicit.
- Protect existing files from accidental overwrites.
- Test reopening projects when media files are missing, incomplete, or inaccessible.
- Ensure shutdown and project closure do not silently discard pending recorded data.
### Acceptance criteria
- Recording failures are reported clearly and do not cause unsafe audio-thread behavior.
- Valid recorded material is preserved whenever possible.
- Incomplete recordings and missing media are detected and explained.
- Recording and recovery behavior is covered by automated or repeatable integration tests.
## Phase 14 — Native Plugin, Instrument, and Effect Architecture
**Goal:** Provide a stable internal extension interface before hosting external plugins.
### Tasks
- Finalize the native C node API, including initialization, processing, reset, and destruction.
- Define parameter metadata, defaults, valid ranges, and automation behavior.
- Specify audio channel layouts and MIDI/event handling.
- Define node state serialization and restoration requirements.
- Establish rules for node creation, failure, reconfiguration, and destruction.
- Ensure the GUI uses documented public APIs rather than internal engine structures.
- Provide a small example instrument and effect implemented against the public interface.
- Document ABI/API compatibility expectations for native extensions.
### Acceptance criteria
- A developer can implement a small native instrument or effect using documented interfaces.
- Invalid parameters, unsupported layouts, and failed initialization are handled safely.
- Node state can be saved and restored where required.
- No C++ or FLTK types leak into the public C API.
## Phase 15 — External Plugin Hosting
**Goal:** Add external plugin support only after the internal node lifecycle is reliable.
### Tasks
- Evaluate candidate plugin formats for licensing, dependencies, maintenance, and Linux support.
- Record the selected format and rationale in an architecture decision document.
- Implement plugin discovery and loading outside the real-time callback.
- Map plugin audio ports, parameters, MIDI/events, and channel layouts to the engine's node model.
- Support plugin state save/load and clear reporting for missing or incompatible plugins.
- Test plugins with different channel counts, parameter sets, and processing requirements.
- Define how plugin failures are reported and how the engine recovers.
- Document crash-isolation limitations; an in-process plugin must not be assumed safe merely because the host is safe.
### Acceptance criteria
- A small, documented set of compatible third-party plugins can be loaded, connected, saved, reopened, and played.
- Missing or incompatible plugins do not silently corrupt the project.
- Plugin loading and destruction do not occur in the real-time callback.
- The chosen format's dependencies and licensing are documented.
## Phase 16 — Automation and Expressive Control
**Goal:** Make automation and MIDI control reliable, sample-timed, and usable.
### Tasks
- Support automation for common parameters such as volume, pan, instrument parameters, and effect parameters.
- Define interpolation modes and behavior at clip boundaries.
- Evaluate automation at the correct time and sample offsets for each processing block.
- Smooth parameter changes where needed to avoid zipper noise or audio artifacts.
- Add MIDI controller mapping where appropriate.
- Handle note-off, panic, seek, stop, project teardown, and device disconnect correctly.
- Define deterministic ordering for MIDI and automation events that occur at the same sample position.
- Test overlapping notes, repeated note-ons, and interrupted playback.
### Acceptance criteria
- Automation and MIDI control reproduce consistent results across repeated playback and project reloads.
- Held notes are released safely on stop, panic, seek, and relevant failure paths.
- Event ordering and interpolation behavior are documented and tested.
## Phase 17 — Editing Workflow, Undo/Redo, and Usability
**Goal:** Make common editing tasks efficient and protect users from accidental changes.
### Tasks
- Make common operations undoable, including create, delete, move, trim, duplicate, and connect.
- Define undo behavior for recording and destructive operations.
- Add consistent keyboard shortcuts and context menus for frequently used actions.
- Implement predictable snapping, grid settings, zoom, scrolling, and selection behavior.
- Improve clip labels, track organization, and visual feedback.
- Make destructive actions difficult to trigger accidentally.
- Keep the GUI responsive while audio is running.
- Ensure undo/redo updates project state and the active engine graph consistently.
- Test keyboard focus and accessibility of essential controls where practical.
### Acceptance criteria
- Common editing workflows can be completed without unnecessary dialogs or manual workarounds.
- Undo/redo restores the intended project state and corresponding engine state.
- GUI operations do not block the real-time audio thread.
- Interaction behavior is documented and covered by relevant tests.
## Phase 18 — Project Format, Compatibility, and Portability
**Goal:** Keep project files valid, recoverable, and maintainable over time.
### Tasks
- Version the project format and implement explicit migration logic when the format changes.
- Validate project data before constructing engine objects from it.
- Handle malformed files, unknown node types, missing assets, and unavailable plugins.
- Define project-folder behavior and reliable media path handling.
- Make saving robust against interrupted writes, for example by writing a temporary file and replacing the destination safely where supported.
- Test save/load round trips and migration from every format version that is supported.
- Keep the format documented and preferably human-inspectable.
- Avoid silently discarding unknown data during load/save unless the format policy explicitly requires it.
### Acceptance criteria
- Supported older projects load correctly or produce clear, actionable compatibility errors.
- Malformed project files do not crash the application or trigger unsafe allocations.
- Missing media and plugins are reported clearly.
- Save/load round trips and format migrations have automated tests.
## Phase 19 — Performance, Scalability, and Stress Testing
**Goal:** Measure performance and establish predictable behavior as projects grow.
### Tasks
- Create repeatable benchmarks for increasing node counts and audio channel counts.
- Measure processing time at supported sample rates and block sizes.
- Profile graph compilation separately from real-time audio processing.
- Identify unnecessary buffer copies, allocations, and redundant processing.
- Test large arrangements, many clips, automation events, and active meters.
- Define bounded processing limits and meaningful overload diagnostics.
- Test under CPU pressure and during frequent GUI redraws.
- Optimize only after profiling identifies a meaningful bottleneck.
- Record baseline benchmark results so regressions can be detected.
### Acceptance criteria
- Performance targets and test conditions are documented.
- Repeatable benchmarks cover representative small and large projects.
- Overload behavior is defined and does not cause unbounded work in the callback.
- Significant performance regressions can be detected through repeatable tests.
## Phase 20 — Release Engineering, Packaging, and Maintenance
**Goal:** Make the application straightforward to build, install, use, diagnose, and maintain.
### Tasks
- Provide reproducible release builds and clean build instructions.
- Add Makefile targets for building, testing, installing, and uninstalling.
- Package the application and required resources for the initial supported Linux target.
- Review licenses and attribution for direct and bundled dependencies.
- Document supported audio backends, required system packages, and configuration.
- Add useful crash and error diagnostics without compromising real-time processing.
- Test fresh installations, upgrades, missing dependencies, and removal.
- Publish a basic user manual, developer documentation, and a known-limitations list.
- Define a release checklist and a policy for handling regressions and project-format compatibility.
### Acceptance criteria
- A person other than the primary developer can build or install the application using the documented steps.
- The installed application can complete the supported core workflow.
- Installation and removal are tested on the initial target environment.
- Dependencies, licensing, limitations, and troubleshooting steps are documented.
- A release can be reproduced from a clean checkout with recorded build instructions.
---
## Recommended Execution Order
Reorder the phases when the audit reveals a blocking dependency. Do not mark a phase complete merely because code exists: its acceptance criteria must be demonstrated by builds, tests, or documented manual verification.
## Definition of Done for Each Phase
A phase is complete only when:
- The project builds with warnings enabled.
- Relevant automated tests pass, and manual tests are documented where automation is impractical.
- Error paths, resource ownership, and thread boundaries have been reviewed.
- Real-time audio constraints remain satisfied.
- Documentation is updated alongside API or behavior changes.
- No unrelated functionality was silently removed.
- Untested behavior and known limitations are reported honestly.
- The phase's acceptance criteria are explicitly checked off.
Do not skip phases without documenting why and preserving acceptance criteria.