README.html

<h1>rosegarden-fork: Enhanced version of Rosegarden MIDI sequencer and musical notation editor</h1>

<p><a name="repository_description"></a>
A fork of <a href="#acknowledgment_and_motivation">Rosegarden</a> with new
Matrix Editor, and Loop, Marker, and Chord Name Ruler, features and
improvements.</p>

<h2><br> <a name="contents"></a>
Contents</h2>

<ul>
<li><a href="#license">License</a></li>
<li><a href="#acknowledgment_and_motivation">Acknowledgment and motivation</a></li>
<li><a href="#build_and_installation">Build and installation</a></li>
<li><a href="#new_features">New features</a>

<ul>
<li><a href="#percussion_matrix_editor_unification">Matrix/Percussion Editor unification</a></li>
<li><a href="#color">Color</a></li>
<li><a href="#additional_main_window_features">Additional Main Window features</a></li>
<li><a href="#matrix_editor_tools">Matrix Editor tools</a>

<ul>
<li><a href="#features_in_all_tools">Features in all editing tools</a></li>
<li><a href="#individual_tools">Individual tools</a></li>
</ul></li>
<li><a href="#matrix_editor_panner_features">Matrix Editor Panner features</a></li>
<li><a href="#additional_new_matrix_editor">Additional Matrix Editor features</a></li>
<li><a href="#loop_ruler">Loop Ruler</a></li>
<li><a href="#marker_ruler">Marker Ruler</a></li>
<li><a href="#chord_key_ruler">Chord/Key Ruler (formerly &quot;Chord Name Ruler&quot;)</a></li>
</ul></li>
<li><a href="#screenshots">Screenshots</a></li>
<li><a href="#further_information">Further information</a></li>
<li><a href="#future_work">Future work</a></li>
</ul>

<h2><br> <a name="license"></a>
License</h2>

<p>Rosegarden is a MIDI sequencer and musical notation editor for Linux.</p>

<p>Copyright 2000-2022 The Rosegarden Development Team
<br>Modifications and additions Copyright &copy; 2022 Mark R. Rubin aka &quot;thanks4opensource&quot; aka &quot;thanks4opensrc&quot;</p>

<p>This file is part of Rosegarden.</p>

<p>The Rosegarden program is free software: you can redistribute it
and/or modify it under the terms of the GNU General Public License as
published by the Free Software Foundation, either version 2 of the
License, or (at your option) any later version.</p>

<p>The Rosegarden program is distributed in the hope that it will be
useful, but WITHOUT ANY WARRANTY; without even the implied warranty
of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
General Public License for more details.</p>

<p>You should have received a copy of the <a href="COPYING">GNU General Public License,
version 2</a> along with the Rosegarden program. If not, see
<a href="https://www.gnu.org/licenses/licenses.html">https://www.gnu.org/licenses/licenses.html</a></p>

<h2><br> <a name="acknowledgment_and_motivation"></a>
Acknowledgment and motivation</h2>

<p>This is a fork of Rosegarden, the official source code,
documentation, and downloads for which is available at:</p>

<ul>
<li><a href="https://rosegardenmusic.com/">https://rosegardenmusic.com/</a></li>
<li><a href="https://sourceforge.net/projects/rosegarden/">https://sourceforge.net/projects/rosegarden/</a></li>
<li><a href="https://sourceforge.net/p/rosegarden/git/ci/master/tree/">https://sourceforge.net/p/rosegarden/git/ci/master/tree/</a></li>
<li><a href="https://github.com/tedfelix/rosegarden-official">https://github.com/tedfelix/rosegarden-official</a></li>
</ul>

<p>Although the fork has many new features and improvements, the vast
majority of the code is unchanged from the official sources.
Rosegarden has an incredibly long and deep history (see <a href="https://rosegardenmusic.com/resources/authors/">Origin of a
Legend</a>) representing
literally many man-centuries of work by dozens if not hundreds of
developers, several of whom (in particular the current lead
maintainer) have each devoted over a decade's worth of tireless
effort to Rosegarden. Their work is acknowledged and greatly
appreciated.</p>

<p>Note also that the fork's changes were submitted (and will continue
to be available) for merge into the official project. As of this
writing this has not happened, and in fact it seems unlikely that it
will, either in the foreseeable future or in fact if ever. This
author can only speculate as to why this is the case, but it has been
hinted that changes to Rosegarden's user interface and/or workflow
(beyond the most trivial) are unlikely to be approved based on a
belief that a large user base exists, the majority of whom would not
accept such changes regardless of whether they represent improvements
or not. There also seems to be a premium placed on program stability
(an understandable position, although in this case possibly taken to
an extreme) and changes of the magnitude as those included here
obviously risk undermining that.</p>

<p>Wherever possible, the forked code offers options to use its new
features or revert to the official version's UI and workflows. But
attempts to implement this were impractical in several cases, such as
when already overly complex code would have become too convoluted
(excessive <code>if (official_compatibility == true)</code> conditionals
scattered everywhere) or when doing so would have made no sense (e.g.
maintaining a separate/vestigal/duplicate Percussion Matrix Editor
identical to the new unified <a href="#percussion_matrix_editor_unification">Matrix
Editor</a>).</p>

<p>Caution: As of this writing the fork has had testing solely by the
author, and doubtless contains many bugs. The intent is to fix them
as they are discovered and/or reported (within the caveats of the NO
WARRANTY disclaimers contained in the <a href="#license">license</a>).
However ...</p>

<p><strong>Important:</strong> Do not report any bugs in the fork to the official
Rosegarden sites listed above. The fork is the sole responsibility
its author and and failures in it in no way reflect upon the official
version's maintainers and developers. The only exception is for bugs
that have been separately, independently, and definitively
demonstrated as occurring in the official Rosegarden versions.</p>

<p>In any case, it is the author's belief that the fork may benefit
others (as it has him), and it is therefor offered for use herein.</p>

<h2><br> <a name="build_and_installation"></a>
Build and installation</h2>

<p>The process of building and installing the code is almost identical
to the procedure described in
<a href="README-official.md">README-official.md</a>.</p>

<p>The only change is that the local repository must first be switched
to the <code>thanks4opensrc-devel</code> branch, i.e.:</p>

<pre><code>$ git checkout thanks4opensrc-devel
</code></pre>

<p>before continuing with:</p>

<pre><code>$ mkdir build
$ cd build
$ cmake ..
$ make
</code></pre>

<p>For further information, see <a href="README-official.md">README-official.md</a>.</p>

<h2><br> <a name="new_features"></a>
New features</h2>

<p>As per this repository's description
<a href="#repository_description">above</a>, the majority of the new features
pertain to the Matrix Editor. Users who do not, or only infrequently,
use that facet of Rosegarden will reap less advantage than those who
do, although they may benefit from the included improvements to
the <a href="#loop_ruler">Loop Ruler</a>, <a href="#marker_ruler">Marker Ruler</a>, and/or
<a href="#chord_key_ruler">Chord/Key Ruler</a>.</p>

<p>Many of the features are more complex to describe than they are to
actually use in practice. It is probably better to use the following
documentation as a starting point for exploration and experimentation
rather than reading it in isolation. Users not familiar with (official)
Rosegarden may want to try the matching actions (if any) in that
version -- either before, after, or simultaneously -- if curious
about the differences.</p>

<p>Note: Full usage documentation for almost all new features (limited
only by Qt restrictions) is available via hover/pop-up help and/or
the context help area at the bottom of the Matrix Editor window.</p>

<p><a name="percussion_matrix_editor_unification"></a></p>

<h4>Matrix/Percussion Editor unification</h4>

<ul>
<li><p>The separate &quot;Percussion Matrix Editor&quot; has been eliminated, as the
improved Matrix Editor correctly displays either normal or
percussion segments without requiring the user to explicitly choose
between the two.</p></li>
<li><p>More importantly, the new version correctly displays and allows
editing a mixture of normal and percussion segments when
editing multiple segments simultaneously.</p></li>
</ul>

<p><a name="show_percussion_durations"></a></p>

<ul>
<li>Note that Rosegarden creates percussion &quot;notes&quot; with automatically
determined &quot;durations&quot; (time between MIDI Note On and Note Off
events), either until the next note on the same percussion
instrument or a whole note, whichever is shorter. Percussion note
durations usually only matter for instruments such as Standard
MIDI's &quot;Whistle&quot;, &quot;Long Guiro&quot;, etc., but for edge cases where
viewing/editing the durations is required, the Matrix Editor's
&quot;View -&gt; Notes -&gt; Show percussion durations&quot; checkbox can be turned
on.</li>
</ul>

<p><a name="color"></a></p>

<h4>Color</h4>

<ul>
<li><p>This forked version of Rosegarden uses color more extensively than
the official one. A new Main Window &quot;Edit -&gt; Segment colors&quot; menu
allows automatic setting of some or all segment colors without
having to manually change each one individually. Several coloring
algorithms are available via sub-menu choices.</p></li>
<li><p>Additionally, the same menu's &quot;Display&quot; sub-options allow a choice
of showing segment colors in the main window in the previous
&quot;Selected dark&quot; mode (in which selected segments are darkened while
non-selected ones show their correct color) vs the new, more
logical, &quot;Selected bright&quot; mode (selected segments visually stand
out in their full/normal/bright colors while non-selected ones are
shown with subdued hatched color lines to indicate their current
lower priority).</p></li>
</ul>

<p><a name="additional_main_window_features"></a></p>

<h4>Additional Main Window features</h4>

<ul>
<li>A new &quot;Tracks -&gt; Delete Empty Tracks&quot; menu is useful when loading
a MIDI file for inspection/analysis. Many such files contain
superfluous tracks (titles, etc.) which clutter the interface and
in particular interfere with the automatic coloring of segments
(the short supply of visually contrasting colors is &quot;wasted&quot; on the
empty segments). If a track contains only segments without
notes, this menu option deletes them, saving a time-consuming
search through the entire composition's time range to see if any
off-screen, late occurring notes exist.</li>
</ul>

<p><a name="matrix_editor_tools"></a></p>

<h4>Matrix Editor tools</h4>

<p>In addition to the Percussion Matrix Editor unification described
<a href="#percussion_matrix_editor_unification">above</a>, most of the fork's
features pertain to the Matrix Editor.</p>

<p><a name="note_display"></a></p>

<h5>Note display</h5>

<p>There are multiple new options/modes for displaying notes.</p>

<ul>
<li><p>The &quot;View -&gt; Notes -&gt; Color&quot; options allow showing notes with color
based on velocity (the only option in official Rosegarden), or in
the the note's segment's color (as set in the main window) . This
latter option greatly aids editing multiple segments/instruments
simultaneously. There is also a somewhat less useful
&quot;Segment+velocity&quot; mode which displays the segment color but with
lightness based on velocity, and an &quot;Only active&quot; checkbox for
displaying notes in non-active segments without color (potentially
useful for directing special attention to the segment being edited,
at the cost of losing information regarding what voices the other
notes belong to).</p></li>
<li><p>Update: &quot;View -&gt; Notes -&gt; Color -&gt; Pitch&quot; mode. Notes colored
according to scale degree (solid color) or pattern of alternating
colors from adjacent diatonic notes for out-of-key accidentals.
Colors were chosen in an attempt to visually imply the relative
importance and musical function of each scale degree:</p>

<pre><code>    1st/tonic   bright green
    2nd         dim blue
    3rd         dim cyan
    4th         dim orange
    5th         yellow
    6th         dim red
    7th         dim magenta
</code></pre></li>
<li><p>The &quot;Show percussion durations&quot; menu was described
<a href="#show_percussion_durations">above</a>.</p></li>
<li><p>The &quot;View -&gt; Notes -&gt; Note names&quot; menu contains a large selection
of note naming options. Some are are dependent on the composition's
key at the time of the note, such as &quot;In-key scale degree&quot; (1-7
plus sharps/flats), &quot;Movable-do solfege&quot; (do- or la-based), and
&quot;In-key integers&quot; (12-tone). Others are key-independent: &quot;Concert
pitch&quot; (standard letter names), &quot;Fixed-do solfege&quot;, &quot;Integer&quot;
(12-tone) (all with MIDI octave number), velocity, and raw MIDI
note numbers.</p></li>
<li><p>If the Chord/Key Ruler is active and a note belongs to a chord, it
can also be labeled with an optional suffix describing the note's
function within the chord (enabling the suffix also automatically
activates the ruler if not currently checked &quot;on&quot; in &quot;View -&gt;
Rulers&quot;). The chord note functions can be labeled with either chord
degrees (1 to 7 plus possible &quot;#&quot; or &quot;b&quot;), or 12-tone integers.</p></li>
<li><p>There are several more label variation options, including whether
accidentals in the ambiguous key of C major should be shown as
sharps vs flats. Additionally, observant users may notice subtle and
not-so-subtle changes and improvements such as the scaling of note
label text at extreme horizontal scales, and in the graphical
indication of selected notes.</p></li>
</ul>

<h5>&quot;Tools&quot; and editing workflow</h5>

<ul>
<li><p>The Matrix Editor's &quot;tools&quot; -- MultiTool (formerly Select), Draw,
Erase, Move, Resize, and Velocity -- have been extensively
redesigned and enhanced.</p></li>
<li><p>Complete/comprehensive/accurate help text is displayed at the
bottom of the Matrix Editor window for all tools, describing
options available in the current context (e.g. whether the mouse
pointer is on a note or not, and the state of the mouse buttons and
current in-progress editing task). Additionally, the onscreen mouse
cursor changes to indicate the current editing mode/context.</p></li>
<li><p>Active segment selection: As per mainstream Rosegarden, only notes
in the current active segment can be selected, modified, created,
or erased. The active segment selector roller widget is still
available in the lower left hand corner of the Matrix Editor
window, but the active segment may also be changed via the menu
displayed when right-clicking if not over an existing note, or
even more easily by clicking any note in the segment to be
activated. (Exception: The control key must be held down when doing
so in the Draw tool in order to differentiate segment activation
from note creation.) Note that this is an example of when segment
<a href="#color">colors</a> (enabled via &quot;View -&gt; Notes -&gt; Color -&gt; Segment&quot;
or &quot;Segment+velocity&quot;) greatly aid ease of use.</p></li>
<li><p>&quot;Alternate&quot; tools: Each tool has an associated &quot;alternate tool&quot;
which can be used for a single operation, or toggled on until
released back to the original. The expectation is that experienced
users will do almost all editing either in the MultiTool or the
Draw tool, each of which is an alternate for the other. All editing
tasks can be achieved with the combination of these two tools, with
the choice between which one to use as the &quot;main&quot; tool and which
the alternate driven by whether currently/primarily modifying
existing notes vs creating new ones.</p></li>
<li><p>Regardless the above, the special purpose and now somewhat
superfluous Erase, Move, Resize, and Velocity tools are still
available for ease of use (or simply user preference) when doing
editing specifically tailored to their particular capabilities.
Example: The MultiTool can move, resize, or adjust the velocity of
notes depending on what part of the note is initially clicked, but
when &quot;small&quot; notes (either due to duration, horizontal zoom scaling
of the Matrix Editor, or both) are being edited it is sometimes
hard to click precisely enough to select the desired action. In
that situation and others (e.g. using the Erase Tool's single-click
erase instead of the double-click available in all tools when
erasing many notes) the single-purpose individual tools are easier
to use.</p></li>
</ul>

<p><a name="features_in_all_tools"></a>
The following capabilites are available in any/all tools:</p>

<ul>
<li><p>Selecting note(s):</p>

<ul>
<li>Click a note to select (replaces any previous selection).</li>
<li>Shift-click note to add to selection, or remove if already in
selection.</li>
<li>Click-drag to select multiple notes (replaces any previous selection).</li>
<li>Shift-click-drag to add multiple notes to selection, or remove
from selection if all notes in drag area are already in
selection. (Exception: Must hold Control key in Draw tool to
differentiate from normal note drawing.)</li>
<li>Double-click to delete note(s)

<ul>
<li>Delete clicked note if no existing selection or note not in
selection. Also deselects any existing selected notes.</li>
<li>Delete all notes in selection if clicked note is in selection.</li>
</ul></li>
<li>Right-click

<ul>
<li>If not over note brings up menu with options to switch to
another tool), plus undo/redo, plus change active segment.</li>
<li>If over note brings up Event Properties dialog. Shift-click
for Intrinsics dialog.</li>
</ul></li>
<li>Click non-active segment note to change active segment.
Exception: Must hold Control key in Draw tool to differentiate
from normal note drawing.</li>
</ul></li>
<li><p>Alternate tools:</p>

<ul>
<li>Each tool has an associated &quot;alternate tool&quot; which can be
switched to temporarily or semi-permanently.

<ul>
<li>Middle-click performs a single right-click action in
alternate tool.</li>
<li>CapsLock toggles alternate tool on and off.</li>
</ul></li>
<li>Alternate tools:

<ul>
<li>MultiTool --&gt; Draw</li>
<li>Draw --&gt; MultiTool</li>
<li>Erase --&gt; Draw</li>
<li>Move --&gt; Resize</li>
<li>Resize --&gt; Move</li>
<li>Velocity --&gt; Resize</li>
</ul></li>
</ul></li>
</ul>

<p><a name="individual_tools"></a>
Individual tools:</p>

<ul>
<li>MultiTool (formerly &quot;Select and Edit&quot;):

<ul>
<li>Move, resize, or change velocity of note depending on whether
mouse is in middle 70%, right 15%, or left 15% of note,
respectively.</li>
<li>If percussion segment (and &quot;View -&gt; Notes -&gt; Show percussion
durations&quot; is not checked &quot;on&quot;), move or change velocity
depending on whether mouse is in lower 80% or upper 20% of
note, respectively.</li>
<li>Hold Control to duplicate note(s) before moving.</li>
<li>Hold Shift while moving (normal or with Control/duplicate) to
disable snap to matrix grid.</li>
</ul></li>
<li>Draw tool:

<ul>
<li>Click to create note, drag to resize.</li>
<li>Hold Shift to disable snap to matrix grid.</li>
<li>Control-click on non-active segment note to disable note
drawing and perform normal non-draw-tool change of active
segment.</li>
<li>Control-click-drag when not over note to disable note drawing
and perform normal non-draw-tool click-drag select.</li>
</ul></li>
<li>Erase tool:

<ul>
<li>Click to delete single note if not in selection.</li>
<li>Delete selection if clicked note in selection.</li>
<li>Tool largely superfluous given double-click delete available in
all tools, but convenient (single- vs double-click) if
interactively deleting large numbers of notes not easily
click-drag-selectable.</li>
</ul></li>
<li>Move tool:

<ul>
<li>Same as MultiTool click in middle of note.</li>
<li>Largely superfluous given the above, but convenient for moving
&quot;small&quot; (short duration) notes without necessitating large
horizontal zoom size.</li>
</ul></li>
<li>Resize tool:

<ul>
<li>Same as MultiTool click in rightmost 15% of note.</li>
<li>Similarly superfluous as per comments on Move tool, above.</li>
<li>Will only resize last of tied notes, and only resize those to
right (later music time).</li>
</ul></li>
<li>Velocity tool:

<ul>
<li>Same as MultiTool click in leftmost 15% of note.</li>
<li>Similarly superfluous as per comments on Move tool, above.</li>
</ul></li>
</ul>

<p><a name="matrix_editor_panner_features"></a></p>

<h4>Matrix Editor Panner features</h4>

<ul>
<li><p>New menu with actions to zoom/pan matrix grid to optimally &quot;fit&quot;
notes, i.e. display all onscreen but without any wasted extra
space.</p></li>
<li><p>Choice of fitting notes in currently displayed range of measures,
all notes in composition, or notes in loop range. Last only enabled
if loop range is defined and is active.</p></li>
<li><p>Optionally/additionally zoom horizontally to fit loop range, or
entire composition, to full window grid width. (&quot;Entire composition&quot;
option fairly useless as panner and main window already display
full composition, but included for completeness).</p></li>
<li><p>&quot;Ignore percussion&quot; option. Useful both because MIDI percussion
&quot;note&quot; numbers cover large range of values unrelated to
composition's pitch range (see <a href="#future_work">Future work</a>, below),
but also because percussion notes have invisible durations (unless
View -&gt; Notes -&gt; Show Percussion Durations is checked on) and can
produce unintuitive &quot;fit&quot; results.</p></li>
<li><p>Panner displays context help.</p></li>
<li><p>Matrix editor &quot;zoom&quot; wheels use scaling value of 4th root of 2 (so
4 &quot;clicks&quot; result in 2x size change).</p></li>
</ul>

<p><a name="additional_new_matrix_editor"></a></p>

<h4>Additional Matrix Editor features</h4>

<ul>
<li><p>New highlight (&quot;stripe&quot;) modes: In-key vs accidental, and
alternating light/dark (for percussion segments).</p></li>
<li><p>Visual distinction between vertical lines indicating measures,
beats, and inter-beat grid timing.</p></li>
<li><p>Percussion &quot;notes&quot; are created on the nearest vertical
measure/beat/grid line instead of the nearest earlier time (matches
semantics that drum hits occur on the beat, not between beats).</p></li>
</ul>

<p><a name="extant_key"></a></p>

<ul>
<li><p>&quot;Extant key&quot; display of key in effect at first visible measure
(left side of matrix grid). Shown to left of Chord/Key ruler if
active, or to left of Marker and Loop Rulers if not. Similar to
printed sheet music (but not Rosegarden's notation editor) which
has key signature at beginning of each staff and only small number
of measures in each. Shows key when Chord/Key Ruler not active or
when no key change in currently displayed range of measures (e.g.
canonical case of single key for entire composition).</p></li>
<li><p>Mouse scrollwheel in main grid area, with None/Ctrl/Shift/Alt key
modifiers, singly or in various combinations, allows all possible
pan and zoom movements (vertical, horizontal, both),</p></li>
<li><p>Matrix editor marker (timeline) ruler and note grid correctly
update when time signature is inserted or removed, even if done
externally in main window or notation editor.</p></li>
<li><p>The vertical piano keyboard at the left of the Matrix Editor window
more accurately aligns with the note grid.</p></li>
</ul>

<p>The following changes/improvements to the Rosegarden &quot;rulers&quot;: Loop,
Marker, and Chord Name -- are available (with minor differences) in
the matrix and notation editors, and the main window.</p>

<p><a name="loop_ruler"></a></p>

<h4>Loop Ruler</h4>

<p>The loop ruler has been extended/enhanced in comparison to both the
longstanding implementation in official Rosegarden 21.12 and prior,
and also the as-of-this-writing upcoming changes in 22.12.</p>

<p>The changes largely center around separating loop range definition
from looped playback, and are partially motivated by the fact that
the loop range is additionally used for purposes other than looping
(e.g. selecting notes by time range in the Matrix Editor).</p>

<ul>
<li><p>Looped playback (or or off) is controlled independently by the
&quot;Loop&quot; toggle buttons (keyboard &quot;@&quot; hotkey/accelerator) in the
Main, Transport, Matrix, and Notation Windows. (The buttons are
synchronized together.)</p></li>
<li><p>If a loop range is defined and is active (see immediately below),
looped playback is confined within the range. If not, looped
playback applies to the combined min/max time ranges of the
composition's segments.</p></li>
<li><p>The loop range is defined via mouse right-click-drag in the loop
ruler. It can be adjusted via right-click-drag close to its
beginning or end points</p></li>
<li><p>The range is active immediately after being defined. When active,
its time span is displayed in green. Times before the range are
displayed in red crosshatch, and times after in blue crosshatch.
This aids in knowing whether an offscreen loop range is before or
after the currently zoomed/panned view.</p></li>
<li><p>The loop range is toggled active/displayed vs inactive/invisible
via mouse right-click <em>without</em> drag. If an attempt is made to
toggle it active without first defining the range a warning dialog
appears. (Note the dialog has an option to disable repeated
warnings.)</p></li>
<li><p>The loop range is automatically clipped to the min/max range of the
compostion's segments, both during range definition and afterwards
if segments are modified or removed.</p></li>
<li><p>Playback cursor movement (click, or click-drag) and playback
stop/start (double-click) remains unchanged or slightly improved
(bug fixes).</p></li>
</ul>

<p>Loop range playback with the loop range defined and active behaves as follows:</p>

<ul>
<li><p>Starting playback (play button, double click, spacebar
hotkey/accelerator, etc) starts at the current cursor time if
within the loop range.</p></li>
<li><p>If current time cursor is before the loop range start time, or
at or after its end time, playback jumps to start time before
beginning.</p></li>
<li><p>Stopping playback (play button, double click, etc) leaves the
time cursor at its current position.</p></li>
<li><p>If the looping button is toggled &quot;on&quot;, playback continues to
loop indefinitely. If not, playback stops at the end of the
loop range. The latter allows repeated single playback of the
loop range under manual control (once per playback start).</p></li>
</ul>

<p><a name="marker_ruler"></a></p>

<h4>Marker Ruler</h4>

<p>Several bugs in the Marker Ruler have been fixed, existing
capabilities improved, and new features added.</p>

<ul>
<li><p>If markers have been defined (newly created or loaded along with
composition from file), they are listed in time-sorted order in the
Marker Ruler's right-click menu and can thus be accessed (jumped
to) with a single mouse right-click and menu choice. This is as
compared to official Rosegarden's requirement to double-click to
bring up the &quot;Manage Markers&quot; dialog box, moving the mouse into it,
and then clicking the marker there (all of which is still
supported). Of course clicking on a marker that is currently
visible onscreen (pan/zoom of window) is also still supported but
is less frequently useful (one could simply move the playback
cursor via the Loop Ruler, but neither method is applicable in the
canonical case when the desired marker is not currently visible).</p></li>
<li><p>New markers are created with a default name of &quot;M:B&quot; or &quot;M:B+NT&quot;
where &quot;M&quot; is measure, &quot;B&quot; is beat, and &quot;NT&quot; is musical note time
past the beat if not exactly on it. Compare to official
Rosegarden's &quot;new marker&quot; default name, which is indistinguishable
when used for multiple markers.</p></li>
<li><p>Because the intended use of markers is to allow quick access to
meaningful places in composition (&quot;2nd chorus&quot;, &quot;movement #3,
Allegro&quot;, &quot;horn section enters here&quot;), when adding a new marker the
marker editor is immediately popped up to change the
above-described default time-based name. Keyboard focus is in the
name field to allow immediate editing without an additional mouse
click. If the default &quot;M:B+NT&quot; name is acceptable, clicking &quot;OK&quot;,
&quot;Cancel&quot;, or pressing the &quot;enter&quot; key pops editor down without
change, so this feature requires only one extra click or keypress
when creating a default-named marker. Regardless, if this workflow
is not desired (e.g. a user who frequently accepts the default
time-based name without change, possibly editing it later via
double-click) the feature can be disabled by unchecking the &quot;Edit
immediately after insert&quot; box in the menu.</p></li>
<li><p>Several bug fixes, including:</p>

<ul>
<li>The Main Window's &quot;Composition -&gt; Jump to Next Marker&quot; (and
&quot;Previous&quot;) used order of creation instead of time order for
newly created (vs loaded from file) markers.</li>
<li>&quot;Shift-click to set a range between markers&quot; was similarly
broken (incorrect order, not time-sorted).</li>
</ul></li>
<li><p>Markers have easily visible down-pointing arrow graphic to left of
text indicating exact time position of marker instead of a
difficult-to-see thin vertical line.</p></li>
</ul>

<p><a name="chord_key_ruler"></a></p>

<h4>Chord/Key Ruler (formerly &quot;Chord Name Ruler&quot;)</h4>

<p>The Chord/Key Ruler has been completely rewritten and extended,
along with its underlying chord analysis engine. New features and
changes include:</p>

<ul>
<li><p>Greatly increased number/types of chords: Extended chords through
13ths, augmented/suspended/sixth/altered chords, omit note chords,
etc.</p></li>
<li><p>Show chords, key changes, or both (only key changes in main
window). Key changes overwrite chords -- hold middle button to
temporarily hide.</p></li>
<li><p>Right-click menu action to insert key change (at playback position)
in matrix and notation editors. (Was previously only possible via
unrelated &quot;Segment&quot; menu or using the Event List Editor.)</p></li>
<li><p>Two different chord analysis modes: When notes on/off, or all notes
in a specified time range (supports analyzing arpeggios as chords).
Can specify quantization time for notes on/off mode.</p></li>
<li><p>Extensive user menu/preferences for chord naming (concert pitch
letters, roman numeral scale degrees), (&quot;m&quot;/&quot;min&quot;, &quot;aug&quot;/&quot;+&quot;,
&quot;maj7&quot;/triangle7), (minor chord roman numerals &quot;IIm&quot; vs &quot;ii&quot;), etc.</p></li>
<li><p>Optional &quot;slash chord&quot; analysis/naming with several
menu/preferences options (non-chord bass notes, chord or key/pitch
relative bass note names, simplified chord plus added bass vs
extended chord).</p></li>
<li><p>Simplistic/primitive bass note disambiguation of enharmonic chords
(C6 vs Am7, etc).</p></li>
<li><p>Dialog to choose of subset of segments in matrix or notation editor
to use for notes in chord analysis. Allows limiting excessive
reporting of extended chords by e.g. disabling melody instrument
segments.</p></li>
<li><p>Usage suggestion: Add a segment to control chord analyses (add
missing notes, add bass notes for enharmonic disambiguation, etc.)
The segment can be set &quot;unvoiced&quot; by creating its notes with zero
velocity (or later adjusting them) and/or muting segment's track.</p></li>
<li><p>Chord name ruler action (mouse double-click) to delete key changes
(previously only possible via the Event List Editor).</p></li>
<li><p>&quot;No chord&quot; (&quot;n/c&quot;) labels.</p></li>
<li><p>New option in the Notation Editor's chord name ruler to copy chord
name ruler chords to text annotations (automatic lead sheet
generation). Does not overwrite existing text, so individual chords
can be hand-edited as desired. Or multiple/all chords can be
drag-selected and deleted, chord analysis options changed, and the
new chords copied to text in the missing positions.</p></li>
<li><p>&quot;Extant key&quot; label (see <a href="#extant_key">above</a>) displayed in main
window if chord/key ruler enabled.</p></li>
<li><p>Choice of flats or sharps in key of C major.</p></li>
<li><p>Chord label to right of tick mark (formerly only for key changes).
Rationale: Chords start at time and continue for their note's
durations vs sounding only for one instant.</p></li>
<li><p>Chord and key names are always displayed at correct time in ruler
(previously were &quot;pushed&quot; to right if not enough space). Rationale:
Better to omit information than present false information.</p></li>
<li><p>Right-click menu action to disable display of key changes (useful
if key change overwriting chord name at same time).</p></li>
<li><p>Visual distinction between time tick marks for chords vs key changes.</p></li>
</ul>

<p><a name="general_changes_and_improvements"></a></p>

<h4>General changes and improvements</h4>

<ul>
<li><p>Both playback and time cursor motion (&quot;Rewind to Beginning&quot;, &quot;Fast
Forward to End&quot;) stop and move, respectively, to the combined
min/max limits of the composition's segments instead of to the
compostion's maximum measure number (default 100).</p></li>
<li><p>With default settings for &quot;Track Parameters -&gt; Thru Routing&quot; and
&quot;Instrument Parameters -&gt; Receive external&quot;, incoming MIDI notes
always play using the currently selected track's instrument in
whichever window (main, matrix, or notation) currently has mouse
focus.</p></li>
<li><p>New Preferences -&gt; General -&gt; Behavior option to save .rg files
uncompressed. Useful for RCS/CVS version tracking of compositions.
Note that using <code>git</code> provides few benefits because .rg files are
both standalone and normally already compressed, so git's
sophisticated multi-file versioning isn't applicable, and the
RCS/CVS &quot;diff&quot; approach is more effective than attempting to
re-compress already compressed files.</p></li>
<li><p>True unicode sharp and flat symbols instead of ASCII &quot;#&quot; and &quot;b&quot;.</p></li>
<li><p>Auto-save does <em>not</em> remove &quot;dirty&quot; flag (&quot;*&quot; in window title bar
indicating that changes have been made since last save). Prevents
losing changes if exit without save (because no warning, because
auto-save happened) if offer to restore auto-save at next startup
is ignored. (Auto-save is additional safety, not replacement for,
manual saving.)</p></li>
<li><p>The playback time cursor vertical line's visibility has been
increased in the main window and the matrix editor.</p></li>
<li><p>Codebase cleanup, simplification, and rationalization. First steps
at adding finer-grained internal messaging (Qt signals, Composition
and Segment Observers), and partial removal of excessive/gratuitous
uses of the Qt signal/slot mechanism.</p></li>
</ul>

<h2><br> <a name="screenshots"></a>
Screenshots</h2>

<p>The following screenshots illustrate some of the fork's features,
particularly ones that are missing or differ from those
in <a href="https://github.com/tedfelix/rosegarden-official">rosegarden-official</a>.
Note that the images are intended to illustrate a single feature
each but several options and settings may vary between them in an
attempt to best do so. The important point is that the features are
orthogonal/independent and need not be used in the combinations shown.</p>

<p>Click on any thumbnail to see the full-sized original screenshot.</p>

<h4>Segment colors</h4>

<p>For full documentation see <a href="#color">color</a>, above.</p>

<p>The new &quot;bright when selected&quot; color mode:</p>

<p><a href="./screenshots/selected_bright.png"><img src="./screenshots/thumbnails/selected_bright.png" alt="selected_bright" title="Selected bright" /></a></p>

<p>compared to the classic official Rosegarden scheme:</p>

<p><a href="./screenshots/selected_dark.png"><img src="./screenshots/thumbnails/selected_dark.png" alt="selected_dark" title="Selected dark" /></a></p>

<p>The new option to automatically color segments by type of instrument
(or alternately with random colors or a set chosen for maximum visual
differentiation).</p>

<p><a href="./screenshots/instrument_colors.png"><img src="./screenshots/thumbnails/instrument_colors.png" alt="instrument_colors" title="Instrument Colors" /></a></p>

<h4>Unified matrix/percussion editor</h4>

<p>For full documentation see <a href="#percussion_matrix_editor_unification">matrix/percussion editor unification</a>, above.</p>

<p>The single main window button to bring up the matrix editor:</p>

<p><a href="./screenshots/unified_matrix_editor.png"><img src="./screenshots/thumbnails/unified_matrix_editor.png" alt="unified_matrix_editor" title="Unified Matrix Editor" /></a></p>

<p>The new unified matrix editor simultaneously/correctly displaying
percussion segment &quot;notes&quot; vs normal, pitched instrument notes:</p>

<p><a href="./screenshots/percussion.png"><img src="./screenshots/thumbnails/percussion.png" alt="percussion" title="Percussion and normal segments" /></a></p>

<h4>Looop ruler and matrix editor tools</h4>

<p>For full documentation see <a href="#loop_ruler">loop ruler</a> and <a href="#features_in_all_tools">features in all editing tools</a>, above.</p>

<p>Loop ruler showing loop range in green, times before/after in brown/blue, plus matrix tools right-click menu:</p>

<p><a href="./screenshots/loop_ruler.png"><img src="./screenshots/thumbnails/loop_ruler.png" alt="loop_ruler" title="Loop ruler" /></a></p>

<h4>Matrix editor note labeling and coloring options</h4>

<p>For full documentation see <a href="#note_display">note display</a>, above.</p>

<p>Notes with concert pitch letter names, colored by segment:</p>

<p><a href="./screenshots/notes_letter_names.png"><img src="./screenshots/thumbnails/notes_letter_names.png" alt="notes_letter_names" title="Letter names" /></a></p>

<p>Notes labeled with key/scale degree, colored by segment:</p>

<p><a href="./screenshots/notes_scale_degrees.png"><img src="./screenshots/thumbnails/notes_scale_degrees.png" alt="notes_scale_degrees" title="Scale degree notes" /></a></p>

<p>Notes labeled (and colored) with key-relative pitch:</p>

<p><a href="./screenshots/pitch_colors.png"><img src="./screenshots/thumbnails/pitch_colors.png" alt="pitch_colors" title="Scale degree notes" /></a></p>

<p>Notes labeled and colored with MIDI velocity:</p>

<p><a href="./screenshots/velocity_colors_and_labels.png"><img src="./screenshots/thumbnails/velocity_colors_and_labels.png" alt="velocity_colors_and_labels" title="Velocity notes" /></a></p>

<h4>Chord/key ruler features</h4>

<p>For full documentation see <a href="#chord_key_ruler">chord/key ruler</a>, above.</p>

<p>Chord analysis can be limited to notes from a subset of the displayed segments:</p>

<p><a href="./screenshots/chord_note_segments.png"><img src="./screenshots/thumbnails/chord_note_segments.png" alt="chord_note_segments" title="Active chord analysis segments" /></a></p>

<p>Various chord analysis/naming options ...</p>

<p>Concert pitch letter names:</p>

<p><a href="./screenshots/concert_pitch_chords.png"><img src="./screenshots/thumbnails/concert_pitch_chords.png" alt="concert_pitch_chords" title="Concert pitch chord names" /></a></p>

<p>In-key roman numerals:</p>

<p><a href="./screenshots/roman_numeral_chords.png"><img src="./screenshots/thumbnails/roman_numeral_chords.png" alt="roman_numeral_chords" title="Roman numeral chord names" /></a></p>

<h4>Marker ruler enhancements</h4>

<p>For full documentation see <a href="#marker_ruler">marker ruler</a>, above.</p>

<p>Creating a new marker:</p>

<p><a href="./screenshots/insert_marker.png"><img src="./screenshots/thumbnails/insert_marker.png" alt="insert_marker" title="Insert marker" /></a></p>

<p>Jumping to a marker and/or editing markers:</p>

<p><a href="./screenshots/markers.png"><img src="./screenshots/thumbnails/markers.png" alt="markers" title="Manage markers" /></a></p>

<h4>Matrix editor panner &quot;fit notes&quot;</h4>

<p>Automatic zoom/pan of matrix grid. For full documentation see <a href="#matrix_editor_panner_features">matrix
editor panner features</a>, above.</p>

<p><a href="./screenshots/fit_notes.png"><img src="./screenshots/thumbnails/fit_notes.png" alt="fit_notes" title="Fit visible notes" /></a></p>

<h2><br> <a name="further_information"></a>
Further information</h2>

<p>For further information see <a href="README-official.md">README-official.md</a>
and/or the official Rosegarden links listed
<a href="#acknowledgment_and_motivation">above</a>.</p>

<h2><br> <a name="future_work"></a>
Future work</h2>

<ul>
<li>&quot;See-thru&quot; matrix editor notes for View -&gt; Notes -&gt; Color -&gt;
Segment mode to show mulitple notes at same pitch from different
segments/instruments (&quot;doubled&quot; notes).</li>
<li>Replace current main window &quot;Segment Parameters, Color&quot; chooser
with Qt QColorDialog and internal indexed ColourMap class with
direct Qt QColor RGB (or other, more generalized) (16 bit or float
values, better color space) values. May require revving &quot;.rg&quot;
file format.</li>
<li>User remapping of MIDI percussion notes to vertical position in
matrix editor grid and notation editor staves. Would allow
grouping of percussion instruments together and placement (in
matrix editor) directly above or below composition's pitched
instruments' notes. UI implemented similar to main window's
Tracks -&gt; Move Track Up and Move Track Down menu actions. Option
could/would be ignored by the rare user who fluently plays MIDI
drums on piano keyboard (or other instrument) via muscle memory
that bass drum is pitch B1, snare is D2, low wood block F5, etc.</li>
<li>Optional &quot;smooth scrolling&quot; mode in matrix editor: Time cursor
stays fixed at 1/4 way from left (earliest time) of window and
notes scroll right-to-left across it during playback. Avoids
current &quot;jump&quot; when moving cursor gets close to right side of
window and entire display redraws (moved to the left), requiring
visual refocus/reorientation. (Yes, just like turning the page with
printed sheet music, but we are no longer limited by 600 year old
Gutenberg technology.)</li>
<li>Add <code>--stderr</code> commandline option. If not set, no output to
stderr/stdout except fatal errors output immediately before program
self-abort. Regardless, all warning and information messages
instead/also to new Qt text viewer widget/window, viewable via new
main window &quot;Info&quot; icon/button (added to &quot;Open in Matrix Editor&quot;,
&quot;Open in Notation Editor&quot;, etc. group) or via new &quot;View -&gt;
Windows -&gt; ...&quot; menu (currently missing, editors/viewers only
accessable via icon/buttons or accelerator keybindings). Info
viewer widget/window includes &quot;Clear&quot; button to remove
already-viewed messages.</li>
<li>Non-uniform matrix editor horizontal scaling: Have minimum width
for e.g. quarter notes, possibly same as vertical spacing of
pitches, so are &quot;square&quot;. If measure contains only quarter and/or
longer (half, whole) notes, display as 4x quarter note width. If
has shorter notes (eighth and/or below), scale horizontally so
shortest note is same width as canonical measure's quarter note.
Similar to standard notation (and notation editor).</li>
<li>Add text/lyric ruler for viewing/editing lyrics (or more generic
Rosegarden text events) in matrix editor (and optionally notation
editor).</li>
</ul>