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

Phase 21: add filtered MIDI composition edits and triplet piano-roll grids

Browse source
This commit is contained in:
Johannes Findeisen 2026-10-27 15:34:54 +01:00
commit 73fc5eea8d
12 changed files with 796 additions and 39 deletions
Download patch file Download diff file Expand all files Collapse all files

233
docs/ROADMAP.md
View file

@ -458,6 +458,239 @@ or distro registration is performed. Independent human installation/usability,
physical-device/endurance and listening acceptance remain pending and must be
completed before claiming production qualification.
## Phase 21 — Advanced MIDI and Composition
### Goal
Make MIDI composition expressive and efficient without turning the application into an unnecessarily complicated notation editor.
### Tasks
- Improve piano-roll editing for note creation, selection, movement, resizing, and deletion.
- Support configurable snap and grid resolution, including triplets where practical.
- Add velocity editing and editing for supported MIDI note properties.
- Support MIDI channel and note-range filtering where appropriate.
- Improve quantization, transposition, duplication, and pattern repetition.
- Ensure MIDI event ordering is deterministic, especially when note-off and note-on events share a timestamp.
- Define handling for overlapping notes, repeated notes, and malformed MIDI events.
- Add regression tests for MIDI editing and playback scheduling.
### Acceptance criteria
- Common MIDI editing tasks can be completed without manually editing project files.
- Editing preserves unrelated notes and event properties.
- MIDI scheduling remains deterministic at buffer boundaries and under transport changes.
- MIDI operations are covered by automated tests.
Implemented: transactional C filtered note transforms, nearest-grid quantization,
velocity/channel edits, transposition, bounded fresh-ID repetition and deletion;
piano-roll Notes menu, keyboard commands, configurable straight/triplet grids,
channel/pitch filtering and filtered-set selection. Existing mouse move/resize
and project undo/redo remain supported. Core and GUI regression tests demonstrate
property/other-clip preservation, rollback, undo/redo, adjacent/overlapping notes,
equal-offset caller ordering, exact block partitions and seek chase. See MIDI.md.
No format change, MIDI capture, SMF import, lasso selection or piano-roll zoom;
physical-device and listening validation remain pending.
Acceptance evidence:
- [x] Menu/keyboard/mouse commands edit notes without project-file editing.
- [x] Filtered batch tests preserve unmatched notes and unrelated properties.
- [x] Exact scheduling tests cover buffer boundaries and transport seeks.
- [x] Core composition and GUI undo/redo regressions exercise these operations.
## Phase 22 — Audio Clip Editing and Utility Operations
### Goal
Provide focused, non-destructive audio editing tools for arranging and preparing recorded or imported material.
### Tasks
- Support moving, trimming, splitting, duplicating, and deleting audio clips.
- Define clip-boundary behavior, including fades and source offsets.
- Add non-destructive clip gain and basic fade-in/fade-out controls.
- Support time-stretching and pitch-shifting only after selecting a suitable implementation and quality target; otherwise document them as future work.
- Ensure edits do not unexpectedly modify source audio files.
- Add waveform display caching that never blocks the audio thread.
- Test edits at project boundaries, source-file boundaries, and very short clip lengths.
- Document which operations are destructive and non-destructive.
### Acceptance criteria
- Basic clip editing is predictable and undoable.
- Source files remain unchanged unless a documented destructive operation is explicitly invoked.
- Clip boundaries do not produce unintended clicks from invalid offsets or discontinuities.
- Editing and waveform generation never perform blocking work in the real-time audio callback.
## Phase 23 — Modular Workflow and Routing Refinement
### Goal
Preserve the modular spirit of the application while making complex projects understandable and manageable.
### Tasks
- Refine graph and routing views so signal paths are easy to inspect.
- Make connections, disconnections, and invalid routing states clear.
- Provide useful names and visual distinctions for tracks, instruments, effects, buses, and I/O ports.
- Support track grouping or folders if the project model can represent them cleanly.
- Add routing presets or reusable track templates only if they do not complicate the core model.
- Define behavior for cycles and feedback paths; reject unsupported cycles explicitly.
- Make graph changes transactional so failed edits do not leave partially updated routing.
- Add tests for graph changes while playback is running.
### Acceptance criteria
- Users can inspect and understand a project's signal path.
- Invalid graph edits fail safely and leave the previous valid graph intact.
- Graph updates follow the documented real-time synchronization strategy.
- GUI routing concepts map cleanly to the public C engine API.
## Phase 24 — Mixing and Mastering Essentials
### Goal
Provide the essential mixing controls needed to finish a small or medium-sized project.
### Tasks
- Complete track and bus gain, pan, mute, solo, and metering behavior.
- Define how solo states affect buses, sends, and sidechains.
- Add peak meters with clear units and documented ballistics.
- Add master-bus monitoring and clipping indicators.
- Support routing to buses and auxiliary sends if the graph model supports them.
- Make gain staging explicit and avoid hidden or surprising level changes.
- Document meter tap points and whether values are pre-fader, post-fader, or post-effects.
- Test mute, solo, pan, gain, and routing interactions.
### Acceptance criteria
- Mixer controls behave consistently across tracks, buses, and master output.
- Meter readings correspond to documented signal points and units.
- Solo and mute behavior is covered by automated tests.
- No mixer operation introduces allocations, locks, or other prohibited work in the audio callback.
## Phase 25 — Plugin and Instrument Usability
### Goal
Make instruments and effects practical to use, manage, and diagnose in real projects.
### Tasks
- Improve plugin discovery, insertion, removal, replacement, and ordering.
- Show useful plugin identity and status information, including load failures.
- Define parameter metadata, ranges, defaults, units, and formatting.
- Support parameter reset and safe default values.
- Preserve plugin state across save/load where the plugin API supports it.
- Define behavior when a saved plugin is missing or incompatible.
- Manage plugin UI lifetime separately from engine object lifetime.
- Add tests for plugin lifecycle, state restoration, and failure paths.
- Document plugin API versioning and compatibility expectations.
### Acceptance criteria
- Users can identify and manage loaded instruments and effects without editing configuration files.
- Missing or incompatible plugins produce actionable diagnostics and do not silently corrupt projects.
- Plugin state restoration is tested for supported plugin types.
- The engine remains safe if plugin initialization or processing fails, within the documented failure model.
## Phase 26 — Automation and Control Mapping
### Goal
Enable repeatable changes to mix and instrument parameters over time, with clear timing and ownership rules.
### Tasks
- Define a common parameter identity and metadata model.
- Support automation lanes for a carefully selected set of parameters.
- Define interpolation modes and behavior at clip boundaries.
- Specify how automation interacts with live parameter changes and MIDI control.
- Add control mapping for selected external MIDI controllers if feasible.
- Schedule automation deterministically without allocating memory in the audio callback.
- Define behavior when a target parameter or plugin is missing.
- Test automation at buffer boundaries, during seeks, and across loop points.
- Document precedence rules for automation, controller input, and direct user changes.
### Acceptance criteria
- Supported parameters can be automated and saved in a project.
- Playback produces deterministic automation values for a given project and transport position.
- Missing targets fail safely and are reported to the user.
- Automation processing meets the engine's real-time safety requirements.
## Phase 27 — Editing Workflow, Undo/Redo, and Usability
### Goal
Make common editing actions quick, discoverable, and safe to reverse.
### Tasks
- Audit user-visible editing operations for undo/redo support.
- Implement command-based edits with explicit ownership and rollback behavior.
- Group related low-level changes into one meaningful undo step.
- Define undo behavior for operations affecting engine state or external files.
- Improve keyboard shortcuts, selection behavior, focus handling, and context menus.
- Use confirmation only for genuinely destructive or difficult-to-reverse actions.
- Provide clear feedback for long-running operations and failures.
- Add GUI tests or reproducible manual test procedures for critical workflows.
- Keep presentation logic out of the core C engine.
### Acceptance criteria
- Documented editing operations have predictable undo/redo behavior.
- Undo and redo restore the project model and relevant engine state consistently.
- Failed operations do not leave partial changes behind.
- Common tasks can be completed using documented keyboard and mouse interactions.
## Phase 28 — Project Format, Compatibility, and Portability
### Goal
Make project files robust, diagnosable, and maintainable across application versions and supported systems.
### Tasks
- Version the project format and document its compatibility policy.
- Validate project input before applying it to the live engine.
- Handle missing media, plugins, and external dependencies with clear diagnostics.
- Define relative-path, absolute-path, and media-relocation behavior.
- Add safe migration routines for supported older versions.
- Preserve unknown optional fields where practical, or document when they cannot be preserved.
- Test malformed files, truncated files, oversized input, and invalid values.
- Make saves atomic where the platform permits, using a temporary file and replacement strategy.
- Document portability limits, including plugin and audio-backend dependencies.
### Acceptance criteria
- Invalid project files are rejected safely without partially replacing the current project.
- Save failures do not silently destroy the previous valid project file.
- Version incompatibilities and missing dependencies are clearly reported.
- Supported project versions have migration and regression tests.
## Phase 29 — Performance, Scalability, and Stress Testing
### Goal
Establish measurable performance expectations and verify that larger projects remain stable.
### Tasks
- Define representative test projects and target buffer sizes.
- Measure audio callback duration, deadline misses, CPU use, memory use, and graph rebuild costs.
- Test projects with increasing numbers of tracks, graph nodes, connections, MIDI events, and automation points.
- Test long playback sessions and repeated start, stop, seek, and loop operations.
- Stress-test device changes, plugin failures, missing media, and project reloads.
- Use profiling to identify bottlenecks before introducing optimizations.
- Verify that the real-time callback does not allocate, block on mutexes, perform file I/O, or wait on GUI work.
- Document expected limits and known performance bottlenecks.
- Add sanitizers and static analysis to regular development builds where supported.
### Acceptance criteria
- Performance is measured against documented test cases, not subjective impressions alone.
- Stress tests can run repeatedly and produce reproducible results.
- No known real-time safety violation remains in the engine's own callback path.
- Performance regressions can be detected by repeatable tests or benchmark reports.
## Phase 30 — Release Engineering, Packaging, and Maintenance
### Goal
Turn the application into a maintainable release that users can build, install, run, and troubleshoot.
### Tasks
- Define supported operating systems, compiler versions, and audio backends.
- Document build dependencies and provide clear build and test commands.
- Add install and uninstall targets that respect `PREFIX` and standard directory variables.
- Provide appropriate package metadata and desktop integration where relevant.
- Verify installation paths for binaries, libraries, headers, resources, documentation, and example projects.
- Add version reporting and a concise diagnostic mode where useful.
- Prepare release notes, known limitations, and upgrade guidance.
- Test clean builds from a fresh checkout and installation into a staging directory.
- Define a release checklist covering tests, warnings, packaging, and project compatibility.
- Document how users can report reproducible bugs and how maintainers should triage them.
### Acceptance criteria
- A clean checkout can be built and tested using documented commands.
- Installation works with a configurable prefix and does not overwrite unrelated user files.
- The release includes documentation, known limitations, and a reproducible version identifier.
- The project has a repeatable process for preparing and validating releases.
---
## Recommended Execution Order