MNX specification > MNX reference > Objects > dynamic group

The dynamic group object

Type: Dictionary

Encodes a dynamic value at a given rhythmic position.

This is used for any type of dynamic, from immediate ones (such as "p" or "f") to gradual ones (such as crescendo hairpins).

Various attributes are required only for certain types. For quick reference, here are the required attributes for each "type" value:

To encode a hairpin with both starting and ending dynamic values (such as "p < f"), use two separate dynamic groups:

Attributes

Name Type Required? Description
accentPrefix dynamic prefix No Only valid for type="accent". This encodes the prefix for the dynamic.

For example, for a "sfz" dynamic, the prefix is "s".

If not provided, the default is "s".
accentSuffix dynamic suffix No Only valid for type="accent". This encodes the suffix for the dynamic.

For example, for a "sfz" dynamic, the suffix is "z".

If not provided, the default is "z".
end measure rhythmic position No Required if type is "gradual". This defines the endpoint of the gradual dynamic.
glyphs An array of smufl glyph objects No Optional list of SMuFL glyphs to use when displaying this dynamic.

If this is provided, consuming applications should use these specific glyphs. If this isn't provided, consuming applications should automatically determine the SMuFL glyphs based on "value", "attackValue" and "relativeValue".
orient multi-staff orientation No Where the dynamic group is positioned, relative to the staff.

If not provided, the default value is "auto".
position rhythmic position Yes The rhythmic position at which this dynamic group starts.
prefix string No Optional text to display before the dynamic marking, such as "più".

This is free-form text displayed alongside the marking. It is not related to accentPrefix, which encodes a structural part of an accent marking itself.
relativeValue relative dynamic value No Required if type is "relative".
residualValue dynamic value No Only valid for type="accent". This encodes the dynamic that should be used after the initial accent attack.

For example, this is used for "fp" dynamics, which are a bit of a special case meaning "start playing in f, then immediately reduce dynamics to p." This is encoded as {"value": "f", "residualValue": "p"}.
staff staff number No The staff index to which this dynamic group applies. By default, a dynamic group applies to all staffs in the part.
staffEnd staff number No Only valid for type="gradual." This optionally encodes the staff at which the hairpin ends, for hairpins that are angled diagonally and cross staves.
suffix string No Optional text to display after the dynamic marking, such as "sub.".

This is free-form text displayed alongside the marking. It is not related to accentSuffix, which encodes a structural part of an accent marking itself.
type dynamic group type Yes Distinguishes between different types of dynamics. This can be "immediate" (such as a notated "p"), "gradual" (such as a crescendo hairpin), "accent" (such as "sfz") or "relative" (such as a notated "più p", meaning "quieter").
value dynamic value No Required if type is "immediate". This defines the dynamic value, such as "p" or "f".

For gradual dynamics, this is the dynamic value at the beginning.

For accent dynamics, this is the value of the initial attack (the "f" in "sfz"). See residualValue for the dynamic that applies afterward.
visuallyContinues ID No Points to the ID of the directly previous dynamic group, as a hint to rendering engines that this dynamic group and that previous one should be rendered as a single unit. (Typically this means the dynamics and hairpins are drawn at the same vertical position.)

There is no limit to the length of a "visuallyContinues" chain. For example, it's perfectly OK for three or four dynamic groups to each define "visuallyContinues" pointing at the previous dynamic group.

Encoding this is only strictly necessary if it can't be automatically derived by comparing consecutive dynamic groups' "position" and "end" attributes. Rendering engines are encouraged to determine the visuallyContinues value on their own, if it's not explicitly encoded.
voice voice name No The voice to which this dynamic group applies. By default, a dynamic group applies to all voices in the part.
wedgeType wedge type No Required if type is "gradual". This defines whether the hairpin is gradually opening or gradually closing.

Plus globally available attributes: _c, _x, id

Parent objects

This object is used by the following parent objects:

Examples

This object is used in the following examples:

Dynamic accents