Add velocity key track visualization and offset

juzzlin · juzzlin · commit c72d2da837b4 · 2026-01-22T21:15:29.000+02:00
diff --git a/CHANGELOG b/CHANGELOG
@@ -7,6 +7,8 @@ New features:
 
 * Add option to disable UI updates during playback
 
+* Add velocity key track visualization and offset
+
 Bug fixes:
 
 Other:
diff --git a/README.md b/README.md
@@ -89,6 +89,8 @@ All Arctic Music Project songs:
   - The MIDI controller is routed to the instrument of the selected track
 - Highly adjustable note-off's (global default in ms, per-instrument in ms, manual)
 - Virtual MIDI out port (since 1.0.0+)
+- Velocity key track
+  - Make e.g. your piano have less velocity on higher notes. Super cool!
 
 ### Audio
 - Audio recorder
diff --git a/src/application/application.cpp b/src/application/application.cpp
@@ -620,13 +620,13 @@ void Application::connectTrackSettingsModel()
     });
 
     connect(m_trackSettingsModel.get(), &TrackSettingsModel::testSoundRequested, this, [this](uint8_t velocity) {
-        const auto scaledVelocity = Utils::Midi::scaleVelocityByKey(velocity, 60, m_trackSettingsModel->velocityKeyTrack());
+        const auto scaledVelocity = Utils::Midi::scaleVelocityByKey(velocity, 60, m_trackSettingsModel->velocityKeyTrack(), m_trackSettingsModel->velocityKeyTrackOffset());
         m_midiService->playAndStopMiddleC(m_trackSettingsModel->portName(), m_trackSettingsModel->channel(), scaledVelocity);
     });
 
     connect(m_trackSettingsModel.get(), &TrackSettingsModel::noteOnRequested, this, [this](uint8_t note, uint8_t velocity) {
         if (auto instrument = std::shared_ptr<Instrument> { m_trackSettingsModel->toInstrument() }; instrument) {
-            const auto scaledVelocity = Utils::Midi::scaleVelocityByKey(velocity, note, instrument->settings().midiEffects.velocityKeyTrack);
+            const auto scaledVelocity = Utils::Midi::scaleVelocityByKey(velocity, note, instrument->settings().midiEffects.velocityKeyTrack, instrument->settings().midiEffects.velocityKeyTrackOffset);
             m_midiService->playNote(instrument, { note, scaledVelocity });
         }
     });
diff --git a/src/application/models/track_settings_model.cpp b/src/application/models/track_settings_model.cpp
@@ -225,6 +225,7 @@ void TrackSettingsModel::setInstrumentData(const Instrument & instrument)
 
     setVelocityJitter(instrument.settings().midiEffects.velocityJitter);
     setVelocityKeyTrack(instrument.settings().midiEffects.velocityKeyTrack);
+    setVelocityKeyTrackOffset(instrument.settings().midiEffects.velocityKeyTrackOffset);
 
     m_midiCcModel->setMidiCcSettings(instrument.settings().midiCcSettings);
 
@@ -287,6 +288,7 @@ TrackSettingsModel::InstrumentU TrackSettingsModel::toInstrument() const
 
     settings.midiEffects.velocityJitter = m_midiEffectSettings.velocityJitter;
     settings.midiEffects.velocityKeyTrack = m_midiEffectSettings.velocityKeyTrack;
+    settings.midiEffects.velocityKeyTrackOffset = m_midiEffectSettings.velocityKeyTrackOffset;
 
     settings.midiCcSettings = m_midiCcModel->midiCcSettings();
     instrument->setSettings(settings);
@@ -434,6 +436,21 @@ void TrackSettingsModel::setVelocityKeyTrack(int velocityKeyTrack)
     }
 }
 
+int TrackSettingsModel::velocityKeyTrackOffset() const
+{
+    return m_midiEffectSettings.velocityKeyTrackOffset;
+}
+
+void TrackSettingsModel::setVelocityKeyTrackOffset(int velocityKeyTrackOffset)
+{
+    juzzlin::L(TAG).debug() << "Setting velocty key track offset to " << velocityKeyTrackOffset;
+
+    if (m_midiEffectSettings.velocityKeyTrackOffset != velocityKeyTrackOffset) {
+        m_midiEffectSettings.velocityKeyTrackOffset = velocityKeyTrackOffset;
+        emit velocityKeyTrackOffsetChanged();
+    }
+}
+
 int TrackSettingsModel::autoNoteOffOffset() const
 {
     return m_timingSettings.autoNoteOffOffset;
diff --git a/src/application/models/track_settings_model.hpp b/src/application/models/track_settings_model.hpp
@@ -54,6 +54,7 @@ class TrackSettingsModel : public QObject
     Q_PROPERTY(int transpose READ transpose WRITE setTranspose NOTIFY transposeChanged)
     Q_PROPERTY(int velocityJitter READ velocityJitter WRITE setVelocityJitter NOTIFY velocityJitterChanged)
     Q_PROPERTY(int velocityKeyTrack READ velocityKeyTrack WRITE setVelocityKeyTrack NOTIFY velocityKeyTrackChanged)
+    Q_PROPERTY(int velocityKeyTrackOffset READ velocityKeyTrackOffset WRITE setVelocityKeyTrackOffset NOTIFY velocityKeyTrackOffsetChanged)
     Q_PROPERTY(int autoNoteOffOffset READ autoNoteOffOffset WRITE setAutoNoteOffOffset NOTIFY autoNoteOffOffsetChanged)
     Q_PROPERTY(bool autoNoteOffOffsetEnabled READ autoNoteOffOffsetEnabled WRITE setAutoNoteOffOffsetEnabled NOTIFY autoNoteOffOffsetEnabledChanged)
     
@@ -122,6 +123,8 @@ class TrackSettingsModel : public QObject
     void setVelocityJitter(int velocityJitter);
     int velocityKeyTrack() const;
     void setVelocityKeyTrack(int velocityKeyTrack);
+    int velocityKeyTrackOffset() const;
+    void setVelocityKeyTrackOffset(int velocityKeyTrackOffset);
     int autoNoteOffOffset() const;
     void setAutoNoteOffOffset(int autoNoteOffOffset);
     bool autoNoteOffOffsetEnabled() const;
@@ -167,6 +170,7 @@ class TrackSettingsModel : public QObject
     void transposeChanged();
     void velocityJitterChanged();
     void velocityKeyTrackChanged();
+    void velocityKeyTrackOffsetChanged();
     void autoNoteOffOffsetChanged();
     void autoNoteOffOffsetEnabledChanged();
 
@@ -204,6 +208,7 @@ class TrackSettingsModel : public QObject
     {
         int velocityJitter { 0 };
         int velocityKeyTrack { 0 };
+        int velocityKeyTrackOffset { 0 };
     };
 
     MidiEffectSettings m_midiEffectSettings;
diff --git a/src/application/service/application_service.cpp b/src/application/service/application_service.cpp
@@ -160,7 +160,7 @@ void ApplicationService::requestLiveNoteOn(quint8 key, quint8 octave, quint8 vel
     if (const auto instrument = m_editorService->instrument(m_editorService->position().track); instrument) {
         if (const auto midiNote = NoteConverter::keyAndOctaveToMidiNote(key, octave, instrument->settings().transpose); midiNote.has_value()) {
             juzzlin::L(TAG).debug() << "Live note ON " << midiNote->first << " requested on instrument " << instrument->toString().toStdString();
-            const auto scaledVelocity = Utils::Midi::scaleVelocityByKey(velocity, midiNote->second, instrument->settings().midiEffects.velocityKeyTrack);
+            const auto scaledVelocity = Utils::Midi::scaleVelocityByKey(velocity, midiNote->second, instrument->settings().midiEffects.velocityKeyTrack, instrument->settings().midiEffects.velocityKeyTrackOffset);
             emit liveNoteOnRequested(instrument, { midiNote->second, scaledVelocity });
         }
     } else {
diff --git a/src/common/constants.cpp b/src/common/constants.cpp
@@ -224,6 +224,11 @@ QString xmlKeyVelocityKeyTrack()
     return "velocityKeyTrack";
 }
 
+QString xmlKeyVelocityKeyTrackOffset()
+{
+    return "velocityKeyTrackOffset";
+}
+
 QString xmlKeyAutoNoteOffOffset()
 {
     return "autoNoteOffOffset";
diff --git a/src/common/constants.hpp b/src/common/constants.hpp
@@ -77,10 +77,10 @@ QString xmlKeyCutoff();
 QString xmlKeyDelay();
 QString xmlKeyTranspose();
 
-QString xmlKeyVelocityJitter();
-QString xmlKeyVelocityKeyTrack();
-QString xmlKeyAutoNoteOffOffset();
-
+    QString xmlKeyVelocityJitter();
+    QString xmlKeyVelocityKeyTrack();
+    QString xmlKeyVelocityKeyTrackOffset();
+    QString xmlKeyAutoNoteOffOffset();
 QString xmlKeyIndex();
 
 QString xmlKeyInstrument();
diff --git a/src/common/utils.cpp b/src/common/utils.cpp
@@ -27,13 +27,14 @@
 namespace noteahead::Utils {
 namespace Midi {
 
-uint8_t scaleVelocityByKey(uint8_t velocity, uint8_t note, int keyTrackPercentage)
+uint8_t scaleVelocityByKey(uint8_t velocity, uint8_t note, int keyTrackPercentage, int keyTrackOffset)
 {
     if (keyTrackPercentage <= 0) {
         return velocity;
     }
-    const double factor = 1.0 - (static_cast<double>(keyTrackPercentage) / 100.0) * (static_cast<double>(note) / 127.0);
-    return static_cast<uint8_t>(static_cast<double>(velocity) * factor);
+    const double effectiveNote = std::max(0.0, static_cast<double>(note) - static_cast<double>(keyTrackOffset));
+    const double factor = 1.0 - (static_cast<double>(keyTrackPercentage) / 100.0) * (effectiveNote / 127.0);
+    return static_cast<uint8_t>(std::clamp(static_cast<double>(velocity) * factor, 0.0, 127.0));
 }
 
 double portNameMatchScore(const std::string & s1, const std::string & s2)
diff --git a/src/common/utils.hpp b/src/common/utils.hpp
@@ -34,7 +34,7 @@ QStringList stdStringVectorToQStringList(const std::vector<std::string> & string
 std::optional<double> parseDecimal(std::string_view string);
 } // namespace Misc
 namespace Midi {
-uint8_t scaleVelocityByKey(uint8_t velocity, uint8_t note, int keyTrackPercentage);
+uint8_t scaleVelocityByKey(uint8_t velocity, uint8_t note, int keyTrackPercentage, int keyTrackOffset = 0);
 double portNameMatchScore(const std::string & s1, const std::string & s2);
 } // namespace Midi
 namespace Xml {
diff --git a/src/domain/event.cpp b/src/domain/event.cpp
@@ -77,10 +77,10 @@ void Event::applyVelocityJitter(int percentage)
     }
 }
 
-void Event::applyVelocityKeyTrack(int percentage)
+void Event::applyVelocityKeyTrack(int percentage, int offset)
 {
     if (m_noteData.has_value() && percentage > 0 && m_noteData->type() == NoteData::Type::NoteOn && m_noteData->note().has_value()) {
-        m_noteData->setVelocity(Utils::Midi::scaleVelocityByKey(m_noteData->velocity(), *m_noteData->note(), percentage));
+        m_noteData->setVelocity(Utils::Midi::scaleVelocityByKey(m_noteData->velocity(), *m_noteData->note(), percentage, offset));
     }
 }
 
diff --git a/src/domain/event.hpp b/src/domain/event.hpp
@@ -78,7 +78,7 @@ class Event
     void applyVelocityJitter(int percentage);
 
     //! Applies velocity key track scaling.
-    void applyVelocityKeyTrack(int percentage);
+    void applyVelocityKeyTrack(int percentage, int offset);
 
     //! Convenience function to transpose note data (if set).
     void transpose(int semitones);
diff --git a/src/domain/instrument_settings.cpp b/src/domain/instrument_settings.cpp
@@ -55,6 +55,7 @@ void InstrumentSettings::serializeToXml(QXmlStreamWriter & writer) const
     writer.writeAttribute(Constants::NahdXml::xmlKeyDelay(), QString::number(timing.delay.count()));
     writer.writeAttribute(Constants::NahdXml::xmlKeyVelocityJitter(), QString::number(midiEffects.velocityJitter));
     writer.writeAttribute(Constants::NahdXml::xmlKeyVelocityKeyTrack(), QString::number(midiEffects.velocityKeyTrack));
+    writer.writeAttribute(Constants::NahdXml::xmlKeyVelocityKeyTrackOffset(), QString::number(midiEffects.velocityKeyTrackOffset));
 
     if (timing.autoNoteOffOffset.has_value()) {
         writer.writeAttribute(Constants::NahdXml::xmlKeyAutoNoteOffOffset(), QString::number(timing.autoNoteOffOffset->count()));
@@ -101,6 +102,7 @@ InstrumentSettings::InstrumentSettingsU InstrumentSettings::deserializeFromXml(Q
 
     settings->midiEffects.velocityJitter = Utils::Xml::readIntAttribute(reader, Constants::NahdXml::xmlKeyVelocityJitter(), false).value_or(0);
     settings->midiEffects.velocityKeyTrack = Utils::Xml::readIntAttribute(reader, Constants::NahdXml::xmlKeyVelocityKeyTrack(), false).value_or(0);
+    settings->midiEffects.velocityKeyTrackOffset = Utils::Xml::readIntAttribute(reader, Constants::NahdXml::xmlKeyVelocityKeyTrackOffset(), false).value_or(0);
 
     while (!(reader.isEndElement() && !reader.name().compare(Constants::NahdXml::xmlKeyInstrumentSettings()))) {
         juzzlin::L(TAG).trace() << "InstrumentSettings: Current element: " << reader.name().toString().toStdString();
@@ -133,6 +135,7 @@ QString InstrumentSettings::toString() const
     result += timing.sendMidiClock.has_value() ? QString { ", sendMidiClock=%1" }.arg(timing.sendMidiClock.value() ? Constants::NahdXml::xmlValueTrue() : Constants::NahdXml::xmlValueFalse()) : ", sendMidiClock=None";
     result += QString { ", delay=%1" }.arg(timing.delay.count());
     result += QString { ", velocityKeyTrack=%1" }.arg(midiEffects.velocityKeyTrack);
+    result += QString { ", velocityKeyTrackOffset=%1" }.arg(midiEffects.velocityKeyTrackOffset);
 
     for (auto && midiCcSetting : midiCcSettings) {
         result += " ";
diff --git a/src/domain/instrument_settings.hpp b/src/domain/instrument_settings.hpp
@@ -65,6 +65,7 @@ class InstrumentSettings : public EventData
     {
         int velocityJitter { 0 };
         int velocityKeyTrack { 0 };
+        int velocityKeyTrackOffset { 0 };
     };
 
     MidiEffects midiEffects;
diff --git a/src/domain/song.cpp b/src/domain/song.cpp
@@ -710,7 +710,7 @@ Song::EventList Song::applyInstrumentsOnEvents(EventListCR events) const
                     }
                     event->applyDelay(totalDelay - delayOffset, msPerTick);
                     event->applyVelocityJitter(event->instrument()->settings().midiEffects.velocityJitter);
-                    event->applyVelocityKeyTrack(event->instrument()->settings().midiEffects.velocityKeyTrack);
+                    event->applyVelocityKeyTrack(event->instrument()->settings().midiEffects.velocityKeyTrack, event->instrument()->settings().midiEffects.velocityKeyTrackOffset);
                     event->transpose(event->instrument()->settings().transpose);
                 }
             }
diff --git a/src/unit_tests/song_test/song_test.cpp b/src/unit_tests/song_test/song_test.cpp
@@ -596,6 +596,58 @@ void SongTest::test_renderToEvents_velocityKeyTrackSet_shouldScaleVelocity()
     QCOMPARE(highNoteOn->noteData()->velocity(), 50);
 }
 
+void SongTest::test_renderToEvents_velocityKeyTrackOffsetSet_shouldScaleVelocity()
+{
+    Song song;
+
+    const auto instrument = std::make_shared<Instrument>("TestInstrument");
+    song.setInstrument(0, instrument);
+    auto settings = instrument->settings();
+    settings.midiEffects.velocityKeyTrack = 100; // 100% scaling
+    settings.midiEffects.velocityKeyTrackOffset = 60; // Scaling starts from middle C
+    instrument->setSettings(settings);
+
+    // Note at offset (60) - Should have original velocity
+    // Scaling factor: 1.0 - (1.0 * max(0, 60 - 60) / 127) = 1.0
+    const Position offsetNotePosition = { 0, 0, 0, 0, 0 };
+    song.noteDataAtPosition(offsetNotePosition)->setAsNoteOn(60, 100);
+
+    // Note below offset (40) - Should have original velocity
+    // Scaling factor: 1.0 - (1.0 * max(0, 40 - 60) / 127) = 1.0
+    const Position lowNotePosition = { 0, 0, 0, 1, 0 };
+    song.noteDataAtPosition(lowNotePosition)->setAsNoteOn(40, 100);
+
+    // High note (127) - Should have reduced velocity
+    // Scaling factor: 1.0 - (1.0 * (127 - 60) / 127) = 1.0 - 67/127 ~= 1.0 - 0.527 ~= 0.472
+    // Velocity: 100 * 0.472 ~= 47
+    const Position highNotePosition = { 0, 0, 0, 2, 0 };
+    song.noteDataAtPosition(highNotePosition)->setAsNoteOn(127, 100);
+
+    const auto events = song.renderToEvents(std::make_shared<AutomationService>(), std::make_shared<SideChainService>(), 0);
+
+    auto findNoteOn = [&](uint8_t note) {
+        for (auto && event : events) {
+            if (event->type() == Event::Type::NoteData && event->noteData()->type() == NoteData::Type::NoteOn && event->noteData()->note() == note) {
+                return event;
+            }
+        }
+        return Song::EventS {};
+    };
+
+    const auto offsetNoteOn = findNoteOn(60);
+    QVERIFY(offsetNoteOn);
+    QCOMPARE(offsetNoteOn->noteData()->velocity(), 100);
+
+    const auto lowNoteOn = findNoteOn(40);
+    QVERIFY(lowNoteOn);
+    QCOMPARE(lowNoteOn->noteData()->velocity(), 100);
+
+    const auto highNoteOn = findNoteOn(127);
+    QVERIFY(highNoteOn);
+    // 100 * (1.0 - 67.0/127.0) = 100 * (127-67)/127 = 100 * 60/127 = 6000 / 127 ~= 47.24
+    QCOMPARE(highNoteOn->noteData()->velocity(), 47);
+}
+
 void SongTest::test_renderToEvents_customNoteOffOffsetSet_shouldApplyCorrectOffset()
 {
     Song song;
diff --git a/src/unit_tests/song_test/song_test.hpp b/src/unit_tests/song_test/song_test.hpp
@@ -60,6 +60,7 @@ private slots:
     void test_renderToEvents_transposeSet_shouldApplyTranspose();
     void test_renderToEvents_velocityJitterSet_shouldApplyVelocityJitter();
     void test_renderToEvents_velocityKeyTrackSet_shouldScaleVelocity();
+    void test_renderToEvents_velocityKeyTrackOffsetSet_shouldScaleVelocity();
     void test_renderToEvents_customNoteOffOffsetSet_shouldApplyCorrectOffset();
 
     void test_addTrack_shouldUseSmallestFreeId();
diff --git a/src/view/qml/Components/VirtualKeyboard.qml b/src/view/qml/Components/VirtualKeyboard.qml
@@ -10,6 +10,21 @@ Item {
     signal noteOnRequested(int note)
     signal noteOffRequested(int note)
 
+    property int velocityKeyTrack: 0
+    property int velocityKeyTrackOffset: 0
+
+    function getVelocityColor(note: int, baseColor: color): color {
+        if (velocityKeyTrack <= 0) {
+            return baseColor;
+        }
+        const effectiveNote = Math.max(0, note - velocityKeyTrackOffset);
+        let factor = 1.0 - (velocityKeyTrack / 100.0) * (effectiveNote / 127.0);
+        factor = Math.max(0.0, Math.min(1.0, factor));
+        const c1 = Qt.color("orange");
+        const c2 = Qt.color(baseColor);
+        return Qt.rgba(c1.r + (c2.r - c1.r) * factor, c1.g + (c2.g - c1.g) * factor, c1.b + (c2.b - c1.b) * factor, 1.0);
+    }
+
     // Real piano range: A0 (21) => C8 (108)
     readonly property int baseNote: 21
     readonly property int topNote: 108
@@ -47,7 +62,7 @@ Item {
                     x: index * rootItem.whiteKeyWidth
                     width: rootItem.whiteKeyWidth
                     height: parent.height
-                    color: pressed ? "#e6e6e6" : "#ffffff"
+                    color: pressed ? "#e6e6e6" : rootItem.getVelocityColor(note, "#ffffff")
                     border.color: "#222"
                     border.width: 1
                     property bool pressed: false
@@ -86,7 +101,7 @@ Item {
                     width: rootItem.whiteKeyWidth * 0.6
                     height: parent.height * 0.6
                     radius: 3
-                    color: pressed ? "#222" : "#000"
+                    color: pressed ? "#222" : rootItem.getVelocityColor(note, "#000")
                     border.color: "#111"
                     x: (index + 1) * rootItem.whiteKeyWidth - width / 2
                     y: 0
diff --git a/src/view/qml/Dialogs/TrackSettingsDialog_InstrumentSettings.qml b/src/view/qml/Dialogs/TrackSettingsDialog_InstrumentSettings.qml

Original file line number	Diff line number	Diff line change
`@@ -160,7 +160,7 @@ void ApplicationService::requestLiveNoteOn(quint8 key, quint8 octave, quint8 vel`
`160`	`160`	`if (const auto instrument = m_editorService->instrument(m_editorService->position().track); instrument) {`
`161`	`161`	`if (const auto midiNote = NoteConverter::keyAndOctaveToMidiNote(key, octave, instrument->settings().transpose); midiNote.has_value()) {`
`162`	`162`	`juzzlin::L(TAG).debug() << "Live note ON " << midiNote->first << " requested on instrument " << instrument->toString().toStdString();`
`163`		`- const auto scaledVelocity = Utils::Midi::scaleVelocityByKey(velocity, midiNote->second, instrument->settings().midiEffects.velocityKeyTrack);`
	`163`	`+ const auto scaledVelocity = Utils::Midi::scaleVelocityByKey(velocity, midiNote->second, instrument->settings().midiEffects.velocityKeyTrack, instrument->settings().midiEffects.velocityKeyTrackOffset);`
`164`	`164`	`emit liveNoteOnRequested(instrument, { midiNote->second, scaledVelocity });`
`165`	`165`	`}`
`166`	`166`	`} else {`
Original file line number	Diff line number	Diff line change
`@@ -224,6 +224,11 @@ QString xmlKeyVelocityKeyTrack()`
`224`	`224`	`return "velocityKeyTrack";`
`225`	`225`	`}`
`226`	`226`
	`227`	`+QString xmlKeyVelocityKeyTrackOffset()`
	`228`	`+{`
	`229`	`+ return "velocityKeyTrackOffset";`
	`230`	`+}`
	`231`	`+`
`227`	`232`	`QString xmlKeyAutoNoteOffOffset()`
`228`	`233`	`{`
`229`	`234`	`return "autoNoteOffOffset";`
Original file line number	Diff line number	Diff line change
`@@ -27,13 +27,14 @@`
`27`	`27`	`namespace noteahead::Utils {`
`28`	`28`	`namespace Midi {`
`29`	`29`
`30`		`-uint8_t scaleVelocityByKey(uint8_t velocity, uint8_t note, int keyTrackPercentage)`
	`30`	`+uint8_t scaleVelocityByKey(uint8_t velocity, uint8_t note, int keyTrackPercentage, int keyTrackOffset)`
`31`	`31`	`{`
`32`	`32`	`if (keyTrackPercentage <= 0) {`
`33`	`33`	`return velocity;`
`34`	`34`	`}`
`35`		`- const double factor = 1.0 - (static_cast<double>(keyTrackPercentage) / 100.0) * (static_cast<double>(note) / 127.0);`
`36`		`- return static_cast<uint8_t>(static_cast<double>(velocity) * factor);`
	`35`	`+ const double effectiveNote = std::max(0.0, static_cast<double>(note) - static_cast<double>(keyTrackOffset));`
	`36`	`+ const double factor = 1.0 - (static_cast<double>(keyTrackPercentage) / 100.0) * (effectiveNote / 127.0);`
	`37`	`+ return static_cast<uint8_t>(std::clamp(static_cast<double>(velocity) * factor, 0.0, 127.0));`
`37`	`38`	`}`
`38`	`39`
`39`	`40`	`double portNameMatchScore(const std::string & s1, const std::string & s2)`