Skip to content

armgit / nota

Public Imported from GitHub
0

Nota — a free DAW for macOS, Windows and Linux. No subscription, no account — just open it and make music.

(feat) Return and Master rows show the real volume

Egor Khindikaynen36014fae6d23
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1644defa..470be739 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -42,6 +42,11 @@ Entry categories: `Added`, `Changed`, `Fixed`, `Removed`.
points snap to the grid drawn in the waveform, with the same chip, menu and shortcuts as
the piano roll (they share one setting). Warp markers follow snap on / off and ⌥ — they
used to stick to whole beats.
+- **Levels and volume on Return and Master rows:** the Return and Master rows at the
+ bottom of the arrangement now have a level meter, like the one on every track, and a
+ volume fader with its dB value. Turn up a send and watch the return's meter move, or
+ lower a return or the whole mix without opening the Mixer. Double-click a fader to set
+ it back to 0 dB.
### Changed
- **New projects come ready to play:** a new project — and the workspace Nota opens with —
@@ -69,6 +74,13 @@ Entry categories: `Added`, `Changed`, `Fixed`, `Removed`.
The browser also opens wider by default.
### Fixed
+- **Return and Master rows show the real volume:** a Return row always read −∞ and the
+ Master row always read 0.0, whatever the actual volume. They now show the current
+ volume in dB.
+- **Master volume set in the Mixer is kept:** the Mixer's Master fader started at 0 dB in
+ every project, its changes didn't show in the transport's master control and weren't
+ saved with the project. The Mixer, the transport and the arrangement's Master row now
+ share one master volume, and it's saved.
- **No more clicks when you move filter knobs fast:** quickly turning Freq or Morph on Auto
Filter, or Freq, Gain or Q on EQ-8 and Dynamic EQ-8, could make a click. Steep automation
on these knobs could too. The knobs now glide to the new value over a few milliseconds,
diff --git a/FEATURES.md b/FEATURES.md
index 9928df21..ea9141ff 100644
--- a/FEATURES.md
+++ b/FEATURES.md
@@ -102,6 +102,9 @@ the mixer opens as a separate floating window (**View → Mixer**, ⌘M).
mute/solo and level, and opens to the full control set when selected, so groups read as
families rather than as more tracks. A track without a colour of its own takes its
group's hue, shaded per sibling.
+ - **Return and Master rows stay pinned** under the tracks, each with a level meter, a
+ volume fader and its dB value (the Master fader is the same master volume as the
+ transport's and the Mixer's).
- **Clip names appear where a run begins** — a clip is a colour band over its waveform,
and the name prints only at the head of each run so a repeated pattern reads as one
block. View ▸ Clip names cycles every clip / first of a run / none; a clip named by
diff --git a/specs/005-return-master-meters/checklists/requirements.md b/specs/005-return-master-meters/checklists/requirements.md
new file mode 100644
index 00000000..dd88d48c
--- /dev/null
+++ b/specs/005-return-master-meters/checklists/requirements.md
@@ -0,0 +1,38 @@
+# Specification Quality Checklist: Return & Master Track Levels
+
+**Purpose**: Validate specification completeness and quality before proceeding to planning
+**Created**: 2026-10-13
+**Feature**: [spec.md](../spec.md)
+
+## Content Quality
+
+- [x] No implementation details (languages, frameworks, APIs)
+- [x] Focused on user value and business needs
+- [x] Written for non-technical stakeholders
+- [x] All mandatory sections completed
+
+## Requirement Completeness
+
+- [x] No [NEEDS CLARIFICATION] markers remain
+- [x] Requirements are testable and unambiguous
+- [x] Success criteria are measurable
+- [x] Success criteria are technology-agnostic (no implementation details)
+- [x] All acceptance scenarios are defined
+- [x] Edge cases are identified
+- [x] Scope is clearly bounded
+- [x] Dependencies and assumptions identified
+
+## Feature Readiness
+
+- [x] All functional requirements have clear acceptance criteria
+- [x] User scenarios cover primary flows
+- [x] Feature meets measurable outcomes defined in Success Criteria
+- [x] No implementation details leak into specification
+
+## Notes
+
+- The Nota Context / Current state section names app areas by template design; it is
+ context, not a requirement.
+- FR-006 resolved 2026-10-13: mini volume fader on Return/Master rows, no pan (option B).
+- Default worth confirming: the dB number shows volume, not signal level (matches
+ regular track headers).
diff --git a/specs/005-return-master-meters/contracts/ui-footer-row.md b/specs/005-return-master-meters/contracts/ui-footer-row.md
new file mode 100644
index 00000000..ee784363
--- /dev/null
+++ b/specs/005-return-master-meters/contracts/ui-footer-row.md
@@ -0,0 +1,42 @@
+# UI Contract: Return / Master footer row
+
+The arrangement's pinned footer rows (`ArrangementView`, `FooterRowH = 40`,
+`HeaderW = 228`). Ember tokens per [`DESIGN.md`](../../../DESIGN.md).
+
+## Layout (header column, one row)
+
+```text
+┌─┬──────────────────────────────────────────────┬──┐
+│ │ Reverb 0.0 │▮▮│ ← name (11 SemiBold, TextPrimary) · dB (Mono 9, TextTertiary, 30 px, right-aligned)
+│s│ ━━━━━━━━━━━━━━━━━━━━━━━●────────────── │▮▮│ ← MiniFader, full width of the content column
+└─┴──────────────────────────────────────────────┴──┘
+ 3px spine (track colour; Accent for master / selected) MeterBar, vertical, Width 8, margin 0,6,3,6
+```
+
+- Content padding 8,4 so two lines fit in 40 px; the meter is 28 px tall.
+- The name trims with an ellipsis before the dB read-out or meter shrink.
+- Background: `Brush.SurfaceCard` (return), `Brush.SurfaceRaised` (master), selected →
+ `SelHeaderBg` — unchanged.
+
+## Behaviour
+
+| Interaction | Return row | Master row |
+|---|---|---|
+| Click on the row (not the fader) | selects the return (device chain below) — unchanged | selects the master chain — unchanged |
+| Right-click | Rename / Colour menu — unchanged | unchanged |
+| Drag fader | `SetTrackVolume(returnId)`, dB follows | `Transport.MasterVolume`, dB follows; MST + Mixer follow |
+| Double-click fader | reset to 0 dB | reset to 0 dB |
+| Click meter | clears peak hold (MeterBar default) | same |
+| Browser drop on the row | effect lands on that bus — unchanged | unchanged |
+| Playback with return volume automation | fader + dB follow the live value | n/a (shows set volume) |
+| Automation write | none | none |
+
+## Callbacks added to views
+
+```csharp
+// ArrangementView and MixerView (same shape as SessionView already has)
+public Func<float>? GetMasterVolume { get; set; }
+public Action<float>? SetMasterVolume { get; set; }
+```
+
+Wired in `MainWindow` to `vm.Transport.MasterVolume`.
diff --git a/specs/005-return-master-meters/data-model.md b/specs/005-return-master-meters/data-model.md
new file mode 100644
index 00000000..a3cf8eb3
--- /dev/null
+++ b/specs/005-return-master-meters/data-model.md
@@ -0,0 +1,35 @@
+# Data Model: Return & Master Track Levels
+
+No persisted data changes. The project file format is untouched: return volume is
+already saved per track, master volume already in the project's transport state.
+
+## UI state (ArrangementView, not persisted)
+
+| Element | Per | Source of truth | Read | Write |
+|---|---|---|---|---|
+| Return meter (`MeterBar`, vertical) | return track id | engine track meter | `TryGetTrackMeter(id)` each UI tick (~30 Hz) | — |
+| Master meter (`MeterBar`, vertical) | one | engine master meter | `MasterMeter()` each UI tick | — |
+| Return fader (`MiniFader`, max 1.5, default 1.0) | return track id | engine track volume | `TrackInfo.Volume`, polled in `UpdateMeters` (skipped while dragging) | `SetTrackVolume(id, v)` |
+| Master fader (`MiniFader`, max 1.5, default 1.0) | one | `TransportViewModel.MasterVolume` | `GetMasterVolume()` polled in `UpdateMeters` | `SetMasterVolume(v)` |
+| dB read-out (`TextBlock`, Mono 9) | each fader | the fader's value | — | updated with the fader: `−∞` at ≤ 0.0011, else `0.0` dB |
+
+## Lifetimes
+
+- Footer widgets are recreated by `RebuildFooterHeaders` (refresh, selection change)
+ and registered in footer-only dictionaries cleared there; track-header dictionaries
+ (`_meters`, `_volFaders`, `_volDb`) are not touched by the footer.
+- A rebuilt meter starts empty (peak hold cleared) — the same as track headers after a
+ rebuild.
+
+## Master volume flow (after the change)
+
+```text
+MST fader ─┐
+Mixer ─────┤ ┌─► engine.SetMasterVolume
+Master row ┼─► TransportViewModel.MasterVolume ┼─► project save (transport state)
+MIDI-learn*┤ └─► polled by MST / Mixer / Master row
+Remote ────┘
+```
+
+\* MIDI-learn writes the engine directly (`MidiLearnService`), unchanged by this
+feature — noted as a known gap in research R5's spirit, not fixed here.
diff --git a/specs/005-return-master-meters/plan.md b/specs/005-return-master-meters/plan.md
new file mode 100644
index 00000000..704eb725
--- /dev/null
+++ b/specs/005-return-master-meters/plan.md
@@ -0,0 +1,156 @@
+# Implementation Plan: Return & Master Track Levels
+
+**Branch**: `005-return-master-meters` | **Date**: 2026-10-13 | **Spec**: [spec.md](spec.md)
+
+**Input**: Feature specification from `/specs/005-return-master-meters/spec.md`
+
+## Summary
+
+The arrangement's pinned Return and Master rows get what regular track headers have
+for level: a live vertical stereo `MeterBar`, a `MiniFader` for volume and a real dB
+read-out (today a constant "−∞" / "0.0"). Returns meter and set volume through the
+existing per-track engine calls; the master meters through `MasterMeter()` and sets
+volume through `TransportViewModel.MasterVolume`, the single owner of the master
+volume. `MixerView`, which today keeps a private master volume that is never saved,
+is switched to the same owner. UI-only; no engine or C ABI change. See
+[research.md](research.md).
+
+## Nota: Read Before Planning
+
+- **UI work** → [`DESIGN.md`](../../DESIGN.md) § meters (11/5 stereo, Signal → Caution
+ → Alert, peak hold until clicked, no ballistics — all inherited from `MeterBar`) and
+ the `nota-design` skill.
+- **Anything** → [`CONTRIBUTING.md`](../../CONTRIBUTING.md).
+
+## Technical Context
+
+**Language/Version**: C# / .NET 10 (managed app only)
+
+**Primary Dependencies**: Avalonia (existing); no new dependency
+
+**Storage**: N/A — return volume and master volume are already persisted
+
+**Audio-Thread Impact**: None. UI-thread reads of existing atomic meters
+(`nota_engine_track_meter`, `nota_engine_master_meter`) and existing volume setters.
+
+**Testing**: `scripts/build.sh` (smoke test unchanged); headless Avalonia harness for
+layout, fader and sync checks ([quickstart.md](quickstart.md))
+
+**Target Platform**: macOS / Windows / Linux desktop app
+
+**Project Type**: desktop-app
+
+**Performance Goals**: meters update in the existing ~30 Hz UI tick; ≤ 1 extra
+P/Invoke per return per tick (8 returns → 8 calls, negligible)
+
+**Constraints**: footer row height stays 40 px; header width 228 px
+
+**Scale/Scope**: 2 views + MainWindow wiring; ~150 lines
+
+## Constitution Check
+
+| Principle | Status |
+|---|---|
+| I. Real-time audio safety | ✅ No engine change; reads existing meters from the UI thread |
+| II. Boundary discipline | ✅ Uses existing C ABI calls only |
+| III. Licensing hygiene | ✅ No new source files; no new dependency |
+| IV. Verification gate | ✅ `scripts/build.sh` must pass; engine untouched → no smoke-test extension |
+| V. One logical change | ✅ Arrangement footer levels + the master-volume single-owner fix it depends on (FR-007) |
+| VI. Docs in sync | ⏳ CHANGELOG `[Unreleased]` entries (feat + fix), `nota-features`, `nota-docs` (arrangement page: return/master rows) |
+| VII. Spec-first | ✅ This run |
+| VIII. Rules not weakened | ✅ |
+
+Post-design re-check: unchanged — all gates pass.
+
+## Design
+
+### 1. `ArrangementView` — footer rows ([contract](contracts/ui-footer-row.md))
+
+- `BuildSlimRow` gains a meter, a fader and a live read-out:
+ - Top line: name (`*`) + dB `TextBlock` (Mono 9, 30 px, right-aligned) — the same
+ `ShowDb` formatting as `BuildTrackCard` (factor it into one static helper both use).
+ - Bottom line: `MiniFader { Default = 1.0 }`.
+ - Right: `MeterBar { Width = 8, VerticalAlignment = Stretch, Margin = (0,6,3,6) }`,
+ docked like the track header meter.
+- Return rows: fader `ValueChanged → _engine.SetTrackVolume(id, v)`; initial value
+ from the return's `TrackVM`/`TrackInfo.Volume`.
+- Master row: fader reads `GetMasterVolume()` and writes `SetMasterVolume(v)`.
+- New fields, cleared at the start of `RebuildFooterHeaders`:
+ `_footerMeters : Dictionary<int, MeterBar>`, `_footerFaders : Dictionary<int,
+ MiniFader>`, `_footerDb : Dictionary<int, TextBlock>`, `_masterRowMeter`,
+ `_masterRowFader`, `_masterRowDb`.
+- `UpdateMeters()`:
+ - push `TryGetTrackMeter(id)` into each `_footerMeters` entry (Reset on failure);
+ - push `MasterMeter()` into `_masterRowMeter`;
+ - in the existing per-track loop, also sync `_footerFaders` / `_footerDb` from
+ `ti.Volume` (skip while dragging) — this makes return automation and Mixer/MCP
+ changes show;
+ - sync `_masterRowFader` / `_masterRowDb` from `GetMasterVolume()` (skip while
+ dragging).
+- New public callbacks `GetMasterVolume` / `SetMasterVolume`.
+- Unchanged: selection on card press (the fader handles its own press), context menu,
+ drop target, `FooterRowH`.
+
+### 2. `MixerView` — master volume single owner (FR-007)
+
+- Add the same `GetMasterVolume` / `SetMasterVolume` callbacks; remove
+ `_masterVolume`. The master strip's fader starts from `GetMasterVolume()` on
+ `Refresh()`, writes through `SetMasterVolume`, and in `UpdateMeters()` follows
+ `GetMasterVolume()` when not dragging (MST / Master row / Remote changes).
+
+### 3. `MainWindow` wiring
+
+- `Timeline.GetMasterVolume = () => (float)vm.Transport.MasterVolume;`
+ `Timeline.SetMasterVolume = v => vm.Transport.MasterVolume = v;` next to the other
+ `Timeline` hooks; same for `_mixer` at construction.
+
+### 4. Docs
+
+- `CHANGELOG.md` `[Unreleased]`: Added — level meter and volume fader on Return and
+ Master rows in the arrangement; Fixed — Return rows always showed −∞ and Master 0.0;
+ master volume set in the Mixer was not saved and not shown in the transport.
+- `nota-features`, `nota-docs` skills.
+
+## Project Structure
+
+### Documentation (this feature)
+
+```text
+specs/005-return-master-meters/
+├── spec.md
+├── plan.md # this file
+├── research.md
+├── data-model.md
+├── quickstart.md
+├── contracts/
+│ └── ui-footer-row.md
+├── checklists/
+│ └── requirements.md
+└── tasks.md # /speckit-tasks
+```
+
+### Source Code (repository root)
+
+```text
+src/managed/Nota.App/
+├── ArrangementView.cs # BuildSlimRow, RebuildFooterHeaders, UpdateMeters, callbacks, ShowDb helper
+├── MixerView.cs # master volume through callbacks
+└── MainWindow.axaml.cs # wire Timeline + _mixer to vm.Transport.MasterVolume
+CHANGELOG.md
+FEATURES.md # via nota-features
+```
+
+**Structure Decision**: Managed UI only, inside `Nota.App`; no new projects or files.
+
+## Out of Scope / Known Gaps
+
+- Pan on Return/Master rows (clarified: option B).
+- Recording automation from footer faders; return automation lanes in the footer.
+- Live automated master volume on any master fader (needs an engine read-out).
+- MIDI-learn of Master Volume writes the engine directly, bypassing
+ `Transport.MasterVolume` (`MidiLearnService`) — same class of bug as the Mixer one;
+ candidate for a follow-up.
+
+## Complexity Tracking
+
+No constitution violations.
diff --git a/specs/005-return-master-meters/quickstart.md b/specs/005-return-master-meters/quickstart.md
new file mode 100644
index 00000000..a087dd95
--- /dev/null
+++ b/specs/005-return-master-meters/quickstart.md
@@ -0,0 +1,35 @@
+# Quickstart: validating Return & Master levels
+
+## Automated
+
+```bash
+scripts/build.sh
+```
+
+Must exit green. No engine change, so the smoke test is unchanged.
+
+## Headless UI harness (isolate data with `NOTA_DATA_DIR`)
+
+Recipe: memory "Nota UI verify" — throwaway console project referencing Nota.App,
+`Avalonia.Headless` + Skia, `MainWindow` with its `MainWindowViewModel`, default new
+project (Instrument, Audio, Reverb, Delay returns).
+
+| Check | Expected |
+|---|---|
+| Footer screenshot, Ember Graphite and Ember Paper | Each return and the master row: name, `0.0`, mini fader, vertical meter at the right; row height 40 |
+| Set return volume via engine (`SetTrackVolume(ret, 0.5)`), tick `UpdateMeters` | Return fader moves, read-out `-6.0` |
+| Synthetic drag on a return's fader | Engine return volume changes; Mixer strip shows the same after refresh |
+| Synthetic drag on the master fader | `Transport.MasterVolume` changes; MST fader + dB follow |
+| Change master in `MixerView`, save project, reload | Master row, MST and Mixer all show the saved value |
+| Double-click a footer fader | Back to `0.0` |
+| Add a third return, delete the first | Remaining rows' meters/faders still address their own return |
+| Select a return row repeatedly | Rows rebuild; meters keep updating; no exceptions |
+
+## Manual (when a display is available)
+
+| Step | Expected |
+|---|---|
+| New project, play the instrument track, raise send A | Reverb row meter moves; matches the Mixer's Reverb strip |
+| Mute the Reverb return | Its meter drops to empty |
+| Stop playback | Return/master meters show the tail decaying, then empty |
+| Push the master above 0 dBFS | Master meter's top segment shows Alert; peak hold stays until clicked |
diff --git a/specs/005-return-master-meters/research.md b/specs/005-return-master-meters/research.md
new file mode 100644
index 00000000..45d5781b
--- /dev/null
+++ b/specs/005-return-master-meters/research.md
@@ -0,0 +1,96 @@
+# Research: Return & Master Track Levels
+
+All findings are from the code on `develop` (2026-10-13). No open unknowns remain.
+
+## R1 — Why the rows show "−∞" / "0.0"
+
+- **Finding**: `ArrangementView.BuildSlimRow` (`src/managed/Nota.App/ArrangementView.cs`)
+ prints a constant: `masterSpine ? "0.0" : "−∞"`. No meter, no fader, no binding.
+- **Decision**: Replace the constant with a real volume read-out and add a meter and a
+ mini fader to the slim row.
+
+## R2 — Source of the levels
+
+- **Finding**: The engine already meters returns (render pass 2, `Track::setMeter`,
+ `Engine_Render.cpp`) and the master (`masterPeakL_`…). `nota_engine_track_meter` works
+ for return ids; the Mixer already reads them. For the master id (`kMasterTrackId`),
+ `trackMeter` returns the master *effect-chain* track whose meter is never written —
+ the real master level comes from `nota_engine_master_meter`.
+- **Decision**: Return rows → `TryGetTrackMeter(returnId)`; Master row →
+ `MasterMeter()`. No engine or C ABI change.
+- **Alternatives**: Writing a meter into the master chain track in the engine — rejected,
+ needless engine change.
+
+## R3 — Meter widget and layout in a 40 px row
+
+- **Finding**: Regular track headers use a vertical `MeterBar` (Width 8, margin
+ 0,6,3,6) docked right of the content; group headers use a horizontal 4 px `MeterBar`.
+ `DESIGN.md` § meters: Signal → −6 dB Caution → 0 Alert, −60…+6, peak hold until
+ clicked, no ballistics — all built into `MeterBar`.
+- **Decision**: Same vertical `MeterBar` as track headers (Width 8, docked right,
+ vertical margins 6 → 28 px tall in the 40 px row). Content: name + dB on the top line,
+ `MiniFader` on the bottom line, as the track header's volume row (fader `*`, dB 30 px).
+ The row keeps `FooterRowH = 40`.
+- **Alternatives**: Horizontal 4 px rail like groups — rejected: the request is "the
+ same meter as regular tracks", and a vertical bar reads level better at a glance.
+
+## R4 — Return volume fader
+
+- **Finding**: Returns are ordinary tracks for volume: `SetTrackVolume(id)` and
+ `TrackInfo.Volume` work; `ArrangementView.UpdateMeters` already walks every track
+ (returns included) and pulls `_volFaders[id]` toward the live value (automation).
+ `MiniFader(value, max = 1.5)`, `Default = 1.0` gives double-click reset.
+- **Decision**: Return row fader = `MiniFader(ti.Volume) { Default = 1.0 }`,
+ `ValueChanged → SetTrackVolume`; read-out uses the same `ShowDb` formatting as
+ track headers. Faders/read-outs live in dedicated footer dictionaries (see R6) and
+ are synced in `UpdateMeters`.
+- **Automation write**: Track faders call `BeginAutomationWrite` on gesture. Returns
+ have no visible automation lane in the footer, so recording would create invisible
+ envelopes. **Decision**: no automation write from footer faders (spec FR-006).
+
+## R5 — Master volume: one value
+
+- **Finding**: The master volume's owner is `TransportViewModel.MasterVolume`
+ (`OnMasterVolumeChanged → engine.SetMasterVolume`, saved in the project's transport
+ state, used by MST fader, SessionView mixer, Remote). There is no engine getter.
+ `MixerView` keeps its own `_masterVolume = 1.0f` and calls `engine.SetMasterVolume`
+ directly — it starts at 0 dB regardless of the project and its changes are never
+ saved nor shown in MST (pre-existing bug, conflicts with FR-007).
+- **Decision**: Give `ArrangementView` and `MixerView` the same pair of callbacks
+ `SessionView` already has — `Func<float>? GetMasterVolume`, `Action<float>?
+ SetMasterVolume` — wired in `MainWindow` to `vm.Transport.MasterVolume`. The footer
+ master fader reads/writes through them and is polled in `UpdateMeters` (follows MST,
+ Mixer, MIDI-learn, Remote, load). `MixerView` drops `_masterVolume` in favour of the
+ callbacks.
+- **Master automation**: the engine applies master-volume automation inside the
+ graph without updating the VM, so a fader polling the VM cannot follow it (see R7).
+
+## R6 — Rebuild lifetimes
+
+- **Finding**: `RebuildHeaders` clears `_meters`, `_volFaders`, `_volDb`;
+ `RebuildFooterHeaders` runs separately (on refresh and on every selection change).
+- **Decision**: Footer rows register in their own `_footerMeters` /
+ `_footerFaders` / `_footerDb` (cleared in `RebuildFooterHeaders`) plus a single
+ `_masterMeterBar` / `_masterFader`, so a header rebuild never orphans footer
+ widgets and vice versa. A fader drag must survive `RebuildFooterHeaders` triggered
+ by the click-to-select on the same row: selection happens on `PointerPressed` of the
+ card; the fader marks its press handled, so the row is not rebuilt mid-drag.
+
+## R7 — Live master volume under automation
+
+- **Finding**: `nota_engine.h` has no master-volume getter; master automation is
+ graph-level (`GetMasterVolumeAutomation`).
+- **Decision**: Out of scope to add an engine getter. US4-4 becomes: the master
+ fader shows the master *set* volume (same as MST). Recorded as a spec adjustment.
+
+## R8 — Verification
+
+- No engine change → the smoke test is unchanged; `scripts/build.sh` must still pass.
+- UI is verified with the headless Avalonia harness (see quickstart): MainWindow with
+ its VM, the default template (Reverb/Delay returns), screenshots of the footer in
+ Ember Graphite and Ember Paper; meters driven by real engine readings where the
+ harness can pump audio, otherwise by checking that `UpdateMeters` pushes the
+ engine's return/master readings into the footer bars.
+- Fader behaviour checked with synthetic pointer drags on the footer `MiniFader`s:
+ engine return volume / `Transport.MasterVolume` change, read-outs update, Mixer and
+ MST follow.
diff --git a/specs/005-return-master-meters/spec.md b/specs/005-return-master-meters/spec.md
new file mode 100644
index 00000000..288c2d45
--- /dev/null
+++ b/specs/005-return-master-meters/spec.md
@@ -0,0 +1,240 @@
+# Feature Specification: Return & Master Track Levels
+
+**Feature Branch**: `005-return-master-meters`
+
+**Created**: 2026-10-13
+
+**Status**: Draft
+
+## Clarifications
+
+### Session 2026-10-13
+
+- Q: Should Return/Master rows get the volume fader (and pan) of regular track headers? → A: Volume fader yes, pan no (option B).
+
+**Input**: User description: "Уровни громкости на дорожках Return и Master: сейчас Return всегда показывает минус бесконечность, а Master — 0. Нужно, чтобы они показывали реальный уровень, и чтобы на них был такой же meter, как на обычных дорожках."
+
+## Nota Context *(fill in — drives plan and tasks)*
+
+**Feature area** *(pick the main one)*:
+
+- [ ] Engine (C++, `src/native/nota.engine`) — real-time audio rules apply, see `ARCHITECTURE.md` AR table
+- [ ] Managed app (C#, `src/managed/*`) — domain, application, infrastructure, presentation
+- [x] UI (Avalonia, `src/managed/Nota.Presentation`) — follow `DESIGN.md` (Ember)
+- [ ] Plugin hosting (`pluginhost/`) — the only place JUCE is allowed
+- [ ] Build / packaging / CI (`scripts/`, `.github/`) — see `BUILD.md`
+- [ ] Docs only
+
+**Nota docs to keep in mind** *(links relative to `specs/<slug>/`, where this file lands)*:
+[`ARCHITECTURE.md`](../../ARCHITECTURE.md) (AR rules),
+[`CONTRIBUTING.md`](../../CONTRIBUTING.md) (licensing, dependency policy, PR
+expectations), [`BUILD.md`](../../BUILD.md), [`DESIGN.md`](../../DESIGN.md),
+[`FEATURES.md`](../../FEATURES.md).
+
+**Current state (for reference)**:
+
+- In the arrangement, regular track headers carry a live stereo level meter (vertical
+ bar at the right edge) and a volume fader with a dB read-out; group headers carry a
+ thin horizontal meter.
+- Return and Master rows are slim rows pinned under the tracks. They show only a name
+ and a fixed text: "−∞" on every return, "0.0" on the master. The text never changes —
+ it reflects neither the signal nor the volume. There is no meter.
+- The engine already measures return and master levels: the Mixer strips and the
+ transport's master meter show them live. So the gap is in the arrangement rows only.
+
+## User Scenarios & Testing *(mandatory)*
+
+### User Story 1 - See the return and master levels while playing (Priority: P1)
+
+A user raises a send to the Reverb return and presses play. Next to the return's name
+in the arrangement they see a meter move with the reverb signal, the same way the
+source track's meter moves. The Master row shows the level of the whole mix.
+
+**Why this priority**: It is the core of the request — today these rows give no
+feedback, so the user cannot tell whether a return receives signal or the mix clips
+without opening the Mixer.
+
+**Independent Test**: Play a project with a send raised to a return; watch the return
+and master rows in the arrangement and compare with the same strips in the Mixer.
+
+**Acceptance Scenarios**:
+
+1. **Given** a playing track with a send to return A, **When** the user looks at
+ return A's row, **Then** its meter shows the return's signal, moving in real time.
+2. **Given** a return with no signal (sends at zero, or the return muted), **When**
+ playback runs, **Then** its meter stays empty.
+3. **Given** playback of any non-silent material, **When** the user looks at the
+ Master row, **Then** its meter shows the mix level; when playback stops and tails
+ ring out, the meter falls back to empty.
+4. **Given** the same moment of playback, **When** the user compares a return's or
+ the master's meter in the arrangement with the Mixer, **Then** both show the same
+ level.
+5. **Given** the master is driven above 0 dBFS, **When** it peaks, **Then** the Master
+ meter shows the clip indication the regular track meters show.
+
+---
+
+### User Story 2 - The dB number tells the truth (Priority: P1)
+
+The number printed on the Return and Master rows is no longer a fixed placeholder: it
+shows the real value, the same quantity that regular track headers show next to their
+fader (the track volume in dB).
+
+**Why this priority**: A number that always reads "−∞" on a return that is clearly
+audible is misleading; it is the bug half of the request.
+
+**Independent Test**: Change a return's and the master's volume in the Mixer; read
+the number on their arrangement rows.
+
+**Acceptance Scenarios**:
+
+1. **Given** a return at its default volume, **When** the user looks at its row,
+ **Then** the number reads "0.0", not "−∞".
+2. **Given** a return's or the master's volume changes (Mixer, MST module, return
+ automation, MCP, project load), **When** the change lands, **Then** the row's
+ number updates to the new value in dB.
+3. **Given** a volume at silence, **When** the row is shown, **Then** it reads "−∞",
+ as regular tracks do.
+
+---
+
+### User Story 3 - Return and Master rows look like track rows (Priority: P2)
+
+The meter on the Return and Master rows looks and behaves like the one on regular
+tracks: same colours, scale, peak hold and clip indication, so the arrangement reads
+as one consistent column.
+
+**Why this priority**: Explicit in the request ("такой же meter"), but the value is
+already delivered by Story 1; this story is about visual consistency.
+
+**Independent Test**: Compare a return row and a track row side by side, in both
+Ember Graphite and Ember Paper themes.
+
+**Acceptance Scenarios**:
+
+1. **Given** the arrangement in either theme, **When** the user looks at a return or
+ master row, **Then** its meter uses the same visual style as the track header meter
+ and fits the row without changing the row's height or clipping the name.
+2. **Given** a selected return or master row, **When** it is highlighted, **Then** the
+ meter stays visible and keeps working.
+
+---
+
+### User Story 4 - Adjust return and master volume in place (Priority: P2)
+
+A user hears the reverb is too loud and pulls down the Reverb return's fader right on
+its arrangement row, without opening the Mixer. Same for the master.
+
+**Why this priority**: Chosen in clarification (option B); a convenience on top of
+Stories 1–2.
+
+**Independent Test**: Drag the fader on a return row and on the master row; check the
+sound, the dB read-out, the Mixer and Undo.
+
+**Acceptance Scenarios**:
+
+1. **Given** a return row, **When** the user drags its fader, **Then** the return's
+ volume changes audibly, the row's dB read-out follows, and the Mixer strip shows the
+ same value.
+2. **Given** the master row, **When** the user drags its fader, **Then** the master
+ volume changes and the transport's MST gain shows the same value.
+3. **Given** any of these faders, **When** the user double-clicks it, **Then** it
+ resets to 0 dB.
+4. **Given** volume automation on a return, **When** playback runs, **Then** the
+ return's fader and read-out follow the automated value.
+5. **Given** the master volume changed in the Mixer, **When** the user saves and
+ reopens the project, **Then** the Master row, the MST module and the Mixer all show
+ the saved value.
+
+---
+
+### Edge Cases
+
+- Adding, deleting, renaming or re-colouring a return rebuilds the rows; the meter of
+ each remaining return keeps tracking the right return (no meter shows a neighbour's
+ level).
+- A project with no returns: only the Master row exists and it still meters.
+- Transport stopped: return effect tails still ring out and the return and master
+ meters show them until they decay.
+- A soloed track: returns are exempt from solo, so their meters still move.
+- Very narrow header column: name, number and meter stay legible; the name is cut
+ before the meter disappears.
+- The Mixer and the transport master meter are unaffected.
+
+## Requirements *(mandatory)*
+
+### Functional Requirements
+
+- **FR-001**: Every Return row in the arrangement MUST show a live level meter of that
+ return's output (post its effects and volume), updated at the same rate as regular
+ track meters.
+- **FR-002**: The Master row in the arrangement MUST show a live level meter of the
+ master output, matching the master meter elsewhere in the app.
+- **FR-003**: The Return and Master meters MUST look and behave like the regular track
+ header meter (stereo, same scale, same peak and clip indication, same colours in both
+ themes).
+- **FR-004**: The number on Return and Master rows MUST show the row's current volume in
+ dB, formatted exactly like the regular track header read-out ("−∞" only at silence),
+ and update whenever the volume changes from any source.
+- **FR-005**: Return and Master rows MUST keep their current height, selection,
+ context menu, drop target and automation behaviour.
+- **FR-006**: Return and Master rows MUST carry a mini volume fader like the one on
+ regular track headers (same look, drag, double-click reset to 0 dB). Moving it
+ changes that row's volume and updates the dB read-out; the same value shows in the
+ Mixer and, for the master, in the transport's MST module. A return fader follows that
+ return's volume automation during playback; the Master fader shows the master's set
+ volume, as the MST module does. Like every volume fader in Nota, a move is not an
+ undo step; and like the MST fader, these faders do not record automation (return
+ automation has no visible lane in the arrangement). Pan is NOT added to these rows.
+- **FR-007**: The master volume MUST be one value everywhere: a change in the Mixer,
+ the MST module or the Master row shows in the other two and is what the project
+ saves.
+- **FR-008**: The meters and read-outs MUST stay correct after returns are added,
+ removed, reordered or renamed, after undo/redo of structural edits and after loading a project.
+
+### Key Entities
+
+- **Return row / Master row**: the slim rows pinned under the tracks in the
+ arrangement; each now carries a name, a volume fader with a dB read-out and a live
+ meter.
+
+## Success Criteria *(mandatory)*
+
+### Measurable Outcomes
+
+- **SC-001**: During playback with an active send, a return row's meter visibly moves
+ in 100% of cases; with no signal it stays empty.
+- **SC-002**: At any moment, the level shown on a return or master row differs from the
+ same strip in the Mixer by no more than one meter step.
+- **SC-003**: The dB number on return and master rows matches their actual volume in
+ 100% of checks after changes from the Mixer, MST module, return automation and project load.
+- **SC-004**: Adding the meters causes no noticeable change in UI smoothness with 8
+ returns during playback.
+- **SC-005**: Changing a return's or the master's volume takes one action on its
+ arrangement row, with no need to open the Mixer.
+
+## Assumptions
+
+- The engine already provides live levels and volume control for returns and master; this feature is a UI
+ change only, with no engine or C ABI change.
+- The dB number shows volume (as on regular track headers), not the momentary signal
+ level — the meter shows the signal. This keeps the two kinds of rows consistent.
+- Master volume here is the same master volume as in the transport's MST module and the
+ Mixer — one value, shown in several places.
+- The rows stay 40 px tall; the meter and fader are laid out to fit (exact layout
+ decided in the plan, per `DESIGN.md`).
+- Pan control on Return/Master rows is out of scope (clarified: option B).
+- Showing the live automated master volume on the Master fader is out of scope: the
+ MST module does not show it either, and it would need a new engine read-out.
+- Recording return/master volume automation from these faders is out of scope; return
+ automation lanes in the arrangement footer would be a separate feature.
+
+## Nota Compliance Checklist *(review before implementation; re-check in tasks.md)*
+
+- [ ] Every new source file will carry the AGPL-3.0-only SPDX header (two lines, see CONTRIBUTING.md)
+- [x] No new dependency — or: license checked, AGPL-compatible, `LICENSES/third-party.md` row planned
+- [x] Audio-thread impact considered: no alloc / lock / I/O on the audio thread (AR-6), command queue for data in (AR-4), immutable snapshots for structural edits (AR-5) — reads existing meters from the UI thread only
+- [x] Managed/native crossings go through the pure C ABI in `nota_engine.h` only (AR-7); no JUCE outside `pluginhost/`
+- [x] Smoke-test impact assessed: engine behaviour change → extend `tests/Nota.SmokeTest` — no engine change
+- [ ] User-visible change → `CHANGELOG.md` `[Unreleased]` entry planned (and FEATURES.md / user docs via the nota-features / nota-docs skills)
+- [ ] UI change → follows `DESIGN.md` (Ember design language)
diff --git a/specs/005-return-master-meters/tasks.md b/specs/005-return-master-meters/tasks.md
new file mode 100644
index 00000000..73f1bd8d
--- /dev/null
+++ b/specs/005-return-master-meters/tasks.md
@@ -0,0 +1,156 @@
+---
+
+description: "Tasks for Return & Master track levels"
+---
+
+# Tasks: Return & Master Track Levels
+
+**Input**: Design documents from `/specs/005-return-master-meters/`
+
+**Prerequisites**: [plan.md](plan.md), [spec.md](spec.md), [research.md](research.md), [data-model.md](data-model.md), [contracts/ui-footer-row.md](contracts/ui-footer-row.md), [quickstart.md](quickstart.md)
+
+**Tests**: The spec does not ask for TDD and the engine is untouched (no smoke-test
+extension). Verification is the headless Avalonia harness from
+[quickstart.md](quickstart.md), run per story checkpoint and in the final phase.
+
+**Organization**: Tasks are grouped by user story. Almost all code lives in
+`src/managed/Nota.App/ArrangementView.cs`, so tasks inside it are sequential; the
+`MixerView` and `MainWindow` changes can run in parallel with them.
+
+## Format: `[ID] [P?] [Story] Description`
+
+- **[P]**: Can run in parallel (different files, no dependencies)
+- **[Story]**: Which user story this task belongs to (US1–US4)
+
+---
+
+## Phase 1: Setup
+
+No setup: no new project, file, dependency or tool. Skipped.
+
+---
+
+## Phase 2: Foundational (Blocking Prerequisites)
+
+**Purpose**: The footer row's new skeleton and the master-volume plumbing every story
+builds on.
+
+- [X] T001 In `src/managed/Nota.App/ArrangementView.cs`, extract the track header's dB formatting (`ShowDb` in `BuildTrackCard`, and the duplicate in `UpdateMeters`) into one `private static string VolumeDbText(double v)` returning `"−∞"` when `v <= 0.0011`, else `AudioMath.LinToDb(v).ToString("0.0", NotaNum.Culture)`; use it in both places (note: `UpdateMeters` currently formats without `NotaNum.Culture` — the helper fixes that)
+- [X] T002 In `src/managed/Nota.App/ArrangementView.cs`, add footer-only state next to `_meters`/`_volFaders`/`_volDb`: `_footerMeters : Dictionary<int, MeterBar>`, `_footerFaders : Dictionary<int, MiniFader>`, `_footerDb : Dictionary<int, TextBlock>`, and `_masterRowMeter : MeterBar?`, `_masterRowFader : MiniFader?`, `_masterRowDb : TextBlock?`; clear/null all of them at the top of `RebuildFooterHeaders()` (never in the track-header rebuild that clears `_meters`)
+- [X] T003 In `src/managed/Nota.App/ArrangementView.cs`, add public callbacks `public Func<float>? GetMasterVolume { get; set; }` and `public Action<float>? SetMasterVolume { get; set; }` (same shape as `SessionView.Mixer.cs`), with a one-line comment that `TransportViewModel.MasterVolume` owns the master volume
+- [X] T004 [P] In `src/managed/Nota.App/MainWindow.axaml.cs`, next to the other `Timeline.*` hooks (~line 189), wire `Timeline.GetMasterVolume = () => (float)vm.Transport.MasterVolume;` and `Timeline.SetMasterVolume = v => vm.Transport.MasterVolume = v;`
+- [X] T005 In `src/managed/Nota.App/ArrangementView.cs`, restructure `BuildSlimRow(title, sub, colorIndex, trackId, bgKey, masterSpine)` per [contracts/ui-footer-row.md](contracts/ui-footer-row.md): keep the 3 px spine, card size `HeaderW × FooterRowH` (40), background, selection, right-click menu and `Select` on press; replace the single `Grid` row with a `DockPanel` whose right dock is a slot for the meter and whose content is a two-line `Grid` (row 0: name `*` with `TextTrimming = CharacterEllipsis` + dB `TextBlock` Mono 9, `Brush.TextTertiary`, Width 30, right-aligned; row 1: a slot for the fader), content padding 8,4. Return the parts the callers fill (e.g. an out record with the dock panel, the dB `TextBlock` and the fader slot). Remove the constant `masterSpine ? "0.0" : "−∞"`
+
+**Checkpoint**: The footer renders as before but with the two-line layout and empty slots; app builds.
+
+---
+
+## Phase 3: User Story 1 — See the return and master levels while playing (Priority: P1) 🎯 MVP
+
+**Goal**: Live meters on every Return row and on the Master row.
+
+**Independent Test**: Play with a send raised to a return; the return and master row meters move and match the Mixer strips; a muted return stays empty.
+
+- [X] T006 [US1] In `ArrangementView.RebuildFooterHeaders()` (`src/managed/Nota.App/ArrangementView.cs`), for each return create `new MeterBar { VerticalAlignment = VerticalAlignment.Stretch, Width = 8, Margin = new Thickness(0, 6, 3, 6) }` — exactly the track header meter — dock it right in the row and register it in `_footerMeters[r.Id]`; for the master row create the same and store it in `_masterRowMeter`
+- [X] T007 [US1] In `ArrangementView.UpdateMeters()` (`src/managed/Nota.App/ArrangementView.cs`), push readings: for each `_footerMeters` entry `eng.TryGetTrackMeter(id, out var m) ? bar.Push(m) : bar.Reset()`; `_masterRowMeter?.Push(eng.MasterMeter())` (NOT `TryGetTrackMeter(MasterTrackId)` — that is the master effect-chain track whose meter is never written, research R2)
+- [X] T008 [US1] Headless check per [quickstart.md](quickstart.md): footer meters exist for each return + master, `UpdateMeters` pushes non-zero engine readings into them during playback (or with synthetic readings where audio can't be pumped), muted return → empty
+
+**Checkpoint**: MVP — meters live on Return and Master rows.
+
+---
+
+## Phase 4: User Story 2 — The dB number tells the truth (Priority: P1)
+
+**Goal**: The number on Return/Master rows shows the row's real volume in dB and follows every change.
+
+**Independent Test**: Default return reads `0.0`; changing return/master volume from the Mixer, MST or MCP updates the number; silence reads `−∞`.
+
+- [X] T009 [US2] In `ArrangementView.RebuildFooterHeaders()`, set each return's dB text from `r.Volume` (`TrackVM.Volume`, already filled in `Refresh`) via `VolumeDbText`, and register it in `_footerDb[r.Id]`; set the master's from `GetMasterVolume?.Invoke() ?? 1f` and store it in `_masterRowDb`
+- [X] T010 [US2] In `ArrangementView.UpdateMeters()`, inside the existing `for (i < eng.TrackCount)` loop, also refresh `_footerDb[ti.Id]` from `ti.Volume` (when changed by > 1e-3 from the last shown value); after the loop refresh `_masterRowDb` from `GetMasterVolume()` — this covers Mixer, MST, MCP, Remote, return automation and project load
+- [X] T011 [US2] Headless check: default template returns read `0.0`; `engine.SetTrackVolume(returnId, 0.5f)` + `UpdateMeters()` → `-6.0`; `vm.Transport.MasterVolume = 0.0` → master `−∞`
+
+**Checkpoint**: Return/Master numbers are truthful (the bug half is fixed).
+
+---
+
+## Phase 5: User Story 4 — Adjust return and master volume in place (Priority: P2)
+
+**Goal**: Mini volume faders on Return/Master rows; master volume has one owner everywhere (FR-006, FR-007).
+
+**Independent Test**: Drag a return fader → return volume + Mixer change; drag the master fader → MST follows; Mixer master change survives save/reload.
+
+- [X] T012 [US4] In `ArrangementView.RebuildFooterHeaders()`, put a `MiniFader(volume) { VerticalAlignment = VerticalAlignment.Center, Default = 1.0 }` in each row's fader slot. Return: `ValueChanged += v => { _engine?.SetTrackVolume(id, (float)v); db.Text = VolumeDbText(v); }`, register in `_footerFaders[r.Id]`. Master: initial `GetMasterVolume?.Invoke() ?? 1f`, `ValueChanged += v => { SetMasterVolume?.Invoke((float)v); db.Text = VolumeDbText(v); }`, store in `_masterRowFader`. No `BeginAutomationWrite`/`EndAutomationWrite` (spec FR-006). `MiniFader` marks its press handled, so the card's select-on-press doesn't rebuild the row mid-drag — keep it that way
+- [X] T013 [US4] In `ArrangementView.UpdateMeters()`, sync faders like the track headers do: `_footerFaders[ti.Id]` from `ti.Volume` when `!f.Dragging && |f.Value − ti.Volume| > 1e-3` (return automation, Mixer, MCP); `_masterRowFader` from `GetMasterVolume()` under the same rule; update the paired dB text with `VolumeDbText` (merge with T010 so each value is formatted once)
+- [X] T014 [P] [US4] In `src/managed/Nota.App/MixerView.cs`, add `GetMasterVolume` / `SetMasterVolume` callbacks, remove the private `_masterVolume`; the master strip's `FaderRow(-1, …)` starts from `GetMasterVolume?.Invoke() ?? 1f`, `SetVolume` for `id < 0` calls `SetMasterVolume?.Invoke((float)v)` (no direct `_engine.SetMasterVolume`); in `UpdateMeters()` sync the master fader + dB from `GetMasterVolume()` when not dragging (keep a reference to the master fader/dB `TextBlock` from `FaderRow`)
+- [X] T015 [P] [US4] In `src/managed/Nota.App/MainWindow.axaml.cs`, at `_mixer = new MixerView(vm.Engine) { … }` (~line 369) set `GetMasterVolume = () => (float)vm.Transport.MasterVolume, SetMasterVolume = v => vm.Transport.MasterVolume = v` (depends on T014)
+- [X] T016 [US4] Headless check (synthetic pointer drags, memory recipe): return fader drag changes engine return volume and the dB text; master fader drag changes `vm.Transport.MasterVolume` and the MST read-out; double-click resets to `0.0`; Mixer master change → save → load → Master row, MST and Mixer show the saved value
+
+**Checkpoint**: Faders work; master volume is one value across Mixer, MST and the Master row.
+
+---
+
+## Phase 6: User Story 3 — Return and Master rows look like track rows (Priority: P2)
+
+**Goal**: Visual consistency with track headers in both themes.
+
+**Independent Test**: Side-by-side screenshots of a return row and a track header in Ember Graphite and Ember Paper.
+
+- [X] T017 [US3] Headless screenshots of the arrangement footer + one track header in Ember Graphite and Ember Paper (`NotaThemeService.Set(AppTheme.Light)` by reflection); check against `DESIGN.md` § meters and [contracts/ui-footer-row.md](contracts/ui-footer-row.md): row height 40, meter 28 px tall at the right, name trims before dB/meter shrink, selected row keeps a visible working meter; adjust paddings/margins in `BuildSlimRow` (`src/managed/Nota.App/ArrangementView.cs`) if anything clips
+- [X] T018 [US3] Edge cases from spec: add a third return, delete the first, rename/recolour a return, select rows repeatedly — each remaining row's meter/fader addresses its own return; project with no returns shows only a metering Master row; no exceptions in the log
+
+**Checkpoint**: All four stories done.
+
+---
+
+## Phase 7: Polish & Cross-Cutting Concerns
+
+- [X] T019 Run the full [quickstart.md](quickstart.md) table once more on the final code
+- [X] T020 Remove every temporary harness hook / `// TEMP-VERIFY` line from the repo (harness itself lives under `/tmp`)
+
+### Nota closing tasks *(PR gates)*
+
+- [X] T021 Run `scripts/build.sh` until native + managed + smoke test are green
+- [X] T022 AGPL-3.0-only SPDX header on every new source file — N/A (no new source files)
+- [X] T023 New dependency — N/A
+- [X] T024 `CHANGELOG.md` `[Unreleased]`: Added — level meter and volume fader on Return and Master rows in the arrangement; Fixed — Return rows always showed −∞ and Master 0.0; Fixed — master volume set in the Mixer started at 0 dB, was not saved and did not show in the transport
+- [X] T025 FEATURES.md via the `nota-features` skill; user docs (arrangement page, Return/Master rows; EN + RU) via `nota-docs`; shortcuts — N/A (no new bindings)
+- [X] T026 Engine behaviour change → smoke test — N/A (engine untouched)
+
+---
+
+## Dependencies & Execution Order
+
+- **Foundational (T001–T005)** blocks all stories. T004 is [P] (different file).
+- **US1 (T006–T008)** needs T002, T005.
+- **US2 (T009–T011)** needs T001, T002, T003, T005; independent of US1.
+- **US4 (T012–T016)** needs T003–T005 and US2's read-out (T009/T010 — the fader writes the same dB text). T014 → T015.
+- **US3 (T017–T018)** needs US1 + US2 + US4 rendered (it checks the finished row).
+- **Polish (T019–T026)** last.
+
+Story order: US1 → US2 → US4 → US3 (US3 is a check of the finished row, so it moves after US4).
+
+## Parallel Opportunities
+
+- T004 (`MainWindow.axaml.cs`) alongside T001–T003/T005 (`ArrangementView.cs`).
+- T014 (`MixerView.cs`) alongside T012–T013 (`ArrangementView.cs`); T015 follows T014.
+- Everything else touches `ArrangementView.cs` → sequential.
+
+## Parallel Example: User Story 4
+
+```text
+Task: "T012–T013 footer faders in src/managed/Nota.App/ArrangementView.cs"
+Task: "T014 master volume callbacks in src/managed/Nota.App/MixerView.cs"
+```
+
+## Implementation Strategy
+
+1. Foundational → US1 (meters) → validate: **MVP**, the visible gap is closed.
+2. US2 → the wrong numbers are gone (the bug half of the request).
+3. US4 → faders + the Mixer master-volume fix.
+4. US3 → visual pass in both themes, edge cases.
+5. Polish + closing gates.
+
+## Notes
+
+- Out of scope (plan § Out of Scope): pan on these rows, automation write, live automated master volume, MIDI-learn master-volume bypass.
+- Don't commit — the user reviews and commits.
diff --git a/src/managed/Nota.App/ArrangementView.cs b/src/managed/Nota.App/ArrangementView.cs
index 292973f2..5dae9e6a 100644
--- a/src/managed/Nota.App/ArrangementView.cs
+++ b/src/managed/Nota.App/ArrangementView.cs
@@ -68,6 +68,19 @@ public sealed partial class ArrangementView : UserControl
private readonly Dictionary<int, MiniFader> _volFaders = new();
private readonly Dictionary<int, PanBar> _panBars = new();
private readonly Dictionary<int, TextBlock> _volDb = new();
+ // Return / Master footer rows: meter, volume fader and its dB read-out. Kept apart from the
+ // track-header maps because the two columns are rebuilt independently.
+ private readonly Dictionary<int, MeterBar> _footerMeters = new();
+ private readonly Dictionary<int, MiniFader> _footerFaders = new();
+ private readonly Dictionary<int, TextBlock> _footerDb = new();
+ private MeterBar? _masterRowMeter;
+ private MiniFader? _masterRowFader;
+ private TextBlock? _masterRowDb;
+
+ /// <summary>The master volume lives in <c>TransportViewModel.MasterVolume</c> (saved with the
+ /// project, shown in the MST module); the Master row reads and writes it through these.</summary>
+ public Func<float>? GetMasterVolume { get; set; }
+ public Action<float>? SetMasterVolume { get; set; }
// Per-track header card + its name label, so a selection change repaints just those two
// properties instead of tearing down and rebuilding every header control (click latency).
private readonly Dictionary<int, (Border card, TextBlock name, bool isGroup, Border spine, IBrush spineIdle)> _headerCards = new();
@@ -631,6 +644,15 @@ public sealed partial class ArrangementView : UserControl
if (eng.TryGetTrackMeter(id, out var m)) bar.Push(m);
else bar.Reset();
}
+ foreach (var (id, bar) in _footerMeters)
+ {
+ if (eng.TryGetTrackMeter(id, out var m)) bar.Push(m);
+ else bar.Reset();
+ }
+ // The master level is the engine's master meter; the master *track* is only its effect chain.
+ _masterRowMeter?.Push(eng.MasterMeter());
+ if (GetMasterVolume is { } getMaster)
+ FollowVolume(_masterRowFader, _masterRowDb, getMaster());
int n = eng.TrackCount;
for (int i = 0; i < n; i++)
{
@@ -640,13 +662,24 @@ public sealed partial class ArrangementView : UserControl
{
f.Value = ti.Volume;
if (_volDb.TryGetValue(ti.Id, out var db))
- db.Text = ti.Volume <= 0.0011 ? "−∞" : AudioMath.LinToDb(ti.Volume).ToString("0.0");
+ db.Text = VolumeDbText(ti.Volume);
}
if (_panBars.TryGetValue(ti.Id, out var p) && !p.Dragging && Math.Abs(p.Pan - ti.Pan) > 1e-3)
p.Pan = ti.Pan;
+ if (_footerFaders.TryGetValue(ti.Id, out var rf))
+ FollowVolume(rf, _footerDb.GetValueOrDefault(ti.Id), ti.Volume);
}
}
+ // Moves a footer fader and its read-out to a volume changed elsewhere (Mixer, MST, MCP,
+ // automation, project load) — unless the user is dragging it.
+ private static void FollowVolume(MiniFader? fader, TextBlock? db, double volume)
+ {
+ if (fader is null || fader.Dragging || Math.Abs(fader.Value - volume) <= 1e-3) return;
+ fader.Value = volume;
+ if (db is not null) db.Text = VolumeDbText(volume);
+ }
+
private void Zoom(double factor)
{
_pixelsPerBeat = Math.Clamp(_pixelsPerBeat * factor, 4, 240);
@@ -1810,8 +1843,7 @@ public sealed partial class ArrangementView : UserControl
VerticalAlignment = VerticalAlignment.Center, Width = 30, TextAlignment = TextAlignment.Right,
Margin = new Thickness(6, 0, 0, 0),
};
- void ShowDb(double v) => db.Text = v <= 0.0011 ? "−∞"
- : AudioMath.LinToDb(v).ToString("0.0", NotaNum.Culture);
+ void ShowDb(double v) => db.Text = VolumeDbText(v);
ShowDb(t.Volume);
fader.ValueChanged += v => { _engine?.SetTrackVolume(volTrackId, (float)v); ShowDb(v); };
fader.GestureBegin += () => _engine?.BeginAutomationWrite(volTrackId, AutomationTarget.Volume, -1, -1, "");
@@ -2382,10 +2414,18 @@ public sealed partial class ArrangementView : UserControl
private void RebuildFooterHeaders()
{
_footerHeaders.Children.Clear();
+ _footerMeters.Clear();
+ _footerFaders.Clear();
+ _footerDb.Clear();
double y = 0;
foreach (var r in _returns)
{
- var row = BuildSlimRow(r.Name, "", r.ColorIndex, r.Id, "Brush.SurfaceCard");
+ int id = r.Id;
+ var row = BuildSlimRow(r.Name, r.ColorIndex, id, "Brush.SurfaceCard", r.Volume,
+ v => _engine?.SetTrackVolume(id, (float)v), out var meter, out var fader, out var db);
+ _footerMeters[id] = meter;
+ _footerFaders[id] = fader;
+ _footerDb[id] = db;
Canvas.SetLeft(row, 0);
Canvas.SetTop(row, y);
_footerHeaders.Children.Add(row);
@@ -2394,31 +2434,60 @@ public sealed partial class ArrangementView : UserControl
// Master row: selectable (opens the master effect chain) via the reserved id.
int masterId = _engine?.MasterTrackId ?? -1;
string masterName = _engine is { } me2 && me2.GetTrackName(masterId) is { Length: > 0 } mn ? mn : "Master";
- var master = BuildSlimRow(masterName, "", -1, masterId, "Brush.SurfaceRaised", masterSpine: true);
+ var master = BuildSlimRow(masterName, -1, masterId, "Brush.SurfaceRaised", GetMasterVolume?.Invoke() ?? 1f,
+ v => SetMasterVolume?.Invoke((float)v), out _masterRowMeter, out _masterRowFader, out _masterRowDb,
+ masterSpine: true);
Canvas.SetLeft(master, 0);
Canvas.SetTop(master, y);
_footerHeaders.Children.Add(master);
_footerHeaders.Children.Add(_footerDropRing); // browser drop target (kept invisible until a drag)
}
- private Control BuildSlimRow(string title, string sub, int colorIndex, int trackId, string bgKey, bool masterSpine = false)
+ // A slim footer row: name and volume read-out over a mini fader, with the same vertical
+ // level meter as a track header on the right. No pan, and the fader writes no automation —
+ // returns have no visible lane down here.
+ private Control BuildSlimRow(string title, int colorIndex, int trackId, string bgKey, double volume,
+ Action<double> setVolume, out MeterBar meter, out MiniFader fader, out TextBlock db, bool masterSpine = false)
{
var spineBrush = masterSpine ? NotaPalette.Accent : ClipColors(colorIndex).content;
- var name = new TextBlock { Text = title, FontSize = 11, FontWeight = FontWeight.SemiBold, Foreground = Brush("Brush.TextPrimary"), VerticalAlignment = VerticalAlignment.Center };
- var db = new TextBlock { Text = masterSpine ? "0.0" : "−∞", FontSize = 9, Classes = { "Mono" }, Foreground = Brush("Brush.TextTertiary"), VerticalAlignment = VerticalAlignment.Center };
- var row = new Grid { ColumnDefinitions = new ColumnDefinitions("*,Auto") };
+ var name = new TextBlock
+ {
+ Text = title, FontSize = 11, FontWeight = FontWeight.SemiBold, Foreground = Brush("Brush.TextPrimary"),
+ VerticalAlignment = VerticalAlignment.Center, TextTrimming = TextTrimming.CharacterEllipsis,
+ };
+ var dbText = new TextBlock
+ {
+ Text = VolumeDbText(volume), FontSize = 9, Classes = { "Mono" }, Foreground = Brush("Brush.TextTertiary"),
+ VerticalAlignment = VerticalAlignment.Center, Width = 30, TextAlignment = TextAlignment.Right,
+ Margin = new Thickness(6, 0, 0, 0),
+ };
+ db = dbText;
+ fader = new MiniFader(volume) { VerticalAlignment = VerticalAlignment.Center, Default = 1.0 };
+ fader.ValueChanged += v => { setVolume(v); dbText.Text = VolumeDbText(v); };
+
+ var row = new Grid { ColumnDefinitions = new ColumnDefinitions("*,Auto"), RowDefinitions = new RowDefinitions("*,*") };
Grid.SetColumn(name, 0);
- Grid.SetColumn(db, 1);
+ Grid.SetColumn(dbText, 1);
+ Grid.SetRow(fader, 1);
+ Grid.SetColumnSpan(fader, 2);
row.Children.Add(name);
- row.Children.Add(db);
+ row.Children.Add(dbText);
+ row.Children.Add(fader);
+
+ meter = new MeterBar { VerticalAlignment = VerticalAlignment.Stretch, Width = 8, Margin = new Thickness(0, 6, 3, 6) };
+ DockPanel.SetDock(meter, Dock.Right);
+ var body = new DockPanel
+ {
+ LastChildFill = true,
+ Children = { meter, new Border { Padding = new Thickness(8, 4), Child = row } },
+ };
var spine = new Border { Width = 3, Background = spineBrush };
- var content = new Border { Padding = new Thickness(8, 0), Child = row };
var grid = new Grid { ColumnDefinitions = new ColumnDefinitions("3,*") };
Grid.SetColumn(spine, 0);
- Grid.SetColumn(content, 1);
+ Grid.SetColumn(body, 1);
grid.Children.Add(spine);
- grid.Children.Add(content);
+ grid.Children.Add(body);
bool sel = trackId > 0 && trackId == SelTrackId;
if (sel) spine.Background = NotaPalette.Accent; // selected: brass stripe, name stays Ink 1
@@ -2452,6 +2521,10 @@ public sealed partial class ArrangementView : UserControl
flyout.ShowAt(anchor, showAtPointer: true);
}
+ /// <summary>A volume as the header read-outs print it: dB with one decimal, "−∞" at silence.</summary>
+ private static string VolumeDbText(double v)
+ => v <= 0.0011 ? "−∞" : AudioMath.LinToDb(v).ToString("0.0", NotaNum.Culture);
+
private static IBrush Brush(string key) => (IBrush?)NotaPalette.ByKey(key) ?? NotaPalette.TextPrimary;
// Small bordered "−"/"+" zoom chip (HANDOFF 1b ruler: 11px, bordered, radius 4).
diff --git a/src/managed/Nota.App/Controls/VFader.cs b/src/managed/Nota.App/Controls/VFader.cs
index c035a8f9..871eb28c 100644
--- a/src/managed/Nota.App/Controls/VFader.cs
+++ b/src/managed/Nota.App/Controls/VFader.cs
@@ -21,6 +21,8 @@ internal sealed class VFader : Control
private double _value;
private bool _drag;
public event Action<double>? ValueChanged;
+ public bool Dragging => _drag;
+ public double Value => _value;
public event Action? GestureBegin; // M9-C automation write
public event Action? GestureEnd;
diff --git a/src/managed/Nota.App/MainWindow.axaml.cs b/src/managed/Nota.App/MainWindow.axaml.cs
index 586b0b8f..5d431915 100644
--- a/src/managed/Nota.App/MainWindow.axaml.cs
+++ b/src/managed/Nota.App/MainWindow.axaml.cs
@@ -187,6 +187,8 @@ public partial class MainWindow : Window
_exporter = App.Services.GetRequiredService<IAudioExporter>();
Timeline.Engine = vm.Engine;
+ Timeline.GetMasterVolume = () => (float)vm.Transport.MasterVolume; // Master row fader
+ Timeline.SetMasterVolume = v => vm.Transport.MasterVolume = v;
Timeline.FreezeRole = FreezeRoleOf; // live-freeze (v1.1) header badges
Timeline.FreezeMenuItems = BuildTrackFreezeMenu; // track context menu: Freeze / Live Freeze
Timeline.FreezeTracksMenuItems = BuildTracksFreezeMenu; // multi-track menu: Freeze / Unfreeze all
@@ -366,7 +368,12 @@ public partial class MainWindow : Window
// Mixer lives in its own window (View → Mixer), not as a main-view tab — created here
// once and hosted in the window when opened (see MainWindow.Mixer.cs).
- _mixer = new MixerView(vm.Engine) { IsVisible = false };
+ _mixer = new MixerView(vm.Engine)
+ {
+ IsVisible = false,
+ GetMasterVolume = () => (float)vm.Transport.MasterVolume,
+ SetMasterVolume = v => vm.Transport.MasterVolume = v,
+ };
// Modular: signal-graph view of the selected track (mockup 1a). Follows track
// selection like the Detail device chain does.
diff --git a/src/managed/Nota.App/MixerView.cs b/src/managed/Nota.App/MixerView.cs
index 8664e183..3bf366c8 100644
--- a/src/managed/Nota.App/MixerView.cs
+++ b/src/managed/Nota.App/MixerView.cs
@@ -44,7 +44,12 @@ public sealed class MixerView : UserControl
private readonly List<Control> _sendSections = new();
private readonly List<Control> _ioSections = new();
private bool _sendsVisible = true, _ioVisible = true;
- private float _masterVolume = 1.0f;
+ // The master volume lives in TransportViewModel.MasterVolume (saved with the project, shown
+ // in the MST module and the arrangement's Master row); the master strip goes through these.
+ public Func<float>? GetMasterVolume { get; set; }
+ public Action<float>? SetMasterVolume { get; set; }
+ private VFader? _masterFader;
+ private DragNumber? _masterDb;
public MixerView(IAudioEngine engine)
{
@@ -88,6 +93,12 @@ public sealed class MixerView : UserControl
if (id < 0) meter.Push(_engine.MasterMeter());
else if (_engine.TryGetTrackMeter(id, out var m)) meter.Push(m);
}
+ // Follow master volume changes made elsewhere (MST, Master row, Remote, project load).
+ if (GetMasterVolume is { } get && _masterFader is { Dragging: false } f && _masterDb is { } db)
+ {
+ double v = get();
+ if (Math.Abs(f.Value - v) > 1e-3) { f.SetValueExternal(v); db.Value = LinToDb(v); }
+ }
}
// ---- strips -----------------------------------------------------------
@@ -141,7 +152,7 @@ public sealed class MixerView : UserControl
col.Children.Add(ioRow);
Control db;
- var faderRow = FaderRow(-1, _masterVolume, NotaPalette.Accent, out db, out var meter);
+ var faderRow = FaderRow(-1, GetMasterVolume?.Invoke() ?? 1f, NotaPalette.Accent, out db, out var meter);
_meters.Add((-1, meter));
col.Children.Add(faderRow);
col.Children.Add(db);
@@ -334,7 +345,8 @@ public sealed class MixerView : UserControl
Width = 52, HorizontalAlignment = HorizontalAlignment.Center,
};
ToolTip.SetTip(dbNum, "Set the gain — drag, or double-click to type");
- void SetVolume(double v) { if (id < 0) { _masterVolume = (float)v; _engine.SetMasterVolume(_masterVolume); } else _engine.SetTrackVolume(id, (float)v); }
+ void SetVolume(double v) { if (id < 0) SetMasterVolume?.Invoke((float)v); else _engine.SetTrackVolume(id, (float)v); }
+ if (id < 0) { _masterFader = fader; _masterDb = dbNum; }
fader.ValueChanged += v => { SetVolume(v); dbNum.Value = LinToDb(v); };
dbNum.ValueChanged += d => { double v = DbToLin(d); SetVolume(v); fader.SetValueExternal(v); };
if (id > 0) // M9-C: record volume moves (master volume isn't a track target)