contract_notes

auxjad.mutate.contract_notes(container: Container, max_contraction_duration: Duration, *, minimum_duration: Duration = Duration(0, 1), use_multimeasure_rests: bool = True, rewrite_meter: bool = True) → None

Mutates an input abjad.Container (or child class) in place and has no return value; this function contracts all logical ties (notes and chords) by a maximum contraction duration.

Basic usage:

This function will contract the duration of each logical tie up by the allowed maximum contraction duration.

>>> staff = abjad.Staff(r"c'4 r2. d'2 r2 e'2. r4 f'1")
>>> abjad.show(staff)

>>> auxjad.mutate.contract_notes(staff, abjad.Duration((1, 8)))
>>> abjad.show(staff)

Note

Auxjad automatically adds this function as an extension function to abjad.mutate. It can thus be used from either auxjad.mutate or abjad.mutate namespaces. Therefore, the two lines below are equivalent:

>>> auxjad.mutate.contract_notes(staff)
>>> abjad.mutate.contract_notes(staff)

Chords:

This function works with chords:

>>> staff = abjad.Staff(r"\time 3/4 c'2. <d' e' f'>2 r4 g'4 r2")
>>> abjad.show(staff)

>>> auxjad.mutate.contract_notes(staff, abjad.Duration((1, 16)))
>>> abjad.show(staff)

Second positional argument:

The second positional argument must be an abjad.Duration or objects that can instantiate an abjad.Duration, such as str, tuple, int, and float. The notes will be contract by up to that duration, or until the note is removed:

>>> staff = abjad.Staff(
...     r"c'4 r2. d'2 r2 e'2. r4 f'1"
... )
>>> abjad.show(staff)

>>> auxjad.mutate.contract_notes(staff, abjad.Duration((1, 2)))
>>> abjad.show(staff)

Dynamics:

Dynamics are preserved:

>>> staff = abjad.Staff(r"c'4\ppp r2. d'2\ff r2 e'2.\f r4 f'1\mp")
>>> abjad.show(staff)

>>> auxjad.mutate.contract_notes(staff, abjad.Duration((1, 8)))
>>> abjad.show(staff)

Time signatures changes:

This function handles time signature changes:

>>> staff = abjad.Staff(
...     r"\time 3/4 c'4 r2 "
...     r"\time 2/4 d'2 "
...     r"\time 3/4 e'2. "
...     r"\time 4/4 f'1"
... )
>>> abjad.show(staff)

>>> auxjad.mutate.contract_notes(staff, abjad.Duration((3, 4)))
>>> abjad.show(staff)

minimum_duration:

Use the argument minimum_duration to ensure that notes will not be contracted further than this value:

>>> staff = abjad.Staff(r"c'4 r2. d'2 r2 e'2. r4 f'1")
>>> abjad.show(staff)

>>> auxjad.mutate.contract_notes(staff,
...                            abjad.Duration((1, 2)),
...                            minimum_duration=abjad.Duration((1, 8)),
...                            )
>>> abjad.show(staff)

use_multimeasure_rests:

By default, this function uses multi-measure rests

>>> staff = abjad.Staff(
...     r"\time 4/4 c'4 r2. \time 3/4 d'4 r2 \time 4/4 e'4 r2."
... )
>>> auxjad.mutate.contract_notes(staff, abjad.Duration((1, 2)))
>>> abjad.show(staff)

Set the keyword argument use_multimeasure_rests to False to disable this behaviour.

>>> staff = abjad.Staff(
...     r"\time 4/4 c'4 r2. \time 3/4 d'4 r2 \time 4/4 e'4 r2."
... )
>>> auxjad.mutate.contract_notes(staff,
...                              abjad.Duration((1, 2)),
...                              use_multimeasure_rests=False,
...                              )
>>> abjad.show(staff)

rewrite_meter

By default, this function applies auxjad.mutate.auto_rewrite_meter() at the end of its process.

>>> staff = abjad.Staff(r"\time 3/4 r8 c'8 ~ c'2 r8 d'8 ~ d'2")
>>> abjad.show(staff)

>>> auxjad.mutate.contract_notes(staff, abjad.Duration((1, 8)))
>>> abjad.show(staff)

Set rewrite_meter to False to disable this. The main reason for doing this is performance: when multiple mutations are being applied, it is faster to rewrite the meter just once at the end.

>>> staff = abjad.Staff(r"\time 3/4 r8 c'8 ~ c'2 r8 d'8 ~ d'2")
>>> auxjad.mutate.contract_notes(staff,
...                            abjad.Duration((1, 8)),
...                            rewrite_meter=False,
...                            )
>>> abjad.show(staff)

Warning

This function does not support tuplets. Using a container with one or more tuplets will result in a ValueError exception being raised:

>>> staff = abjad.Staff(r"c'4 r4 \times 2/3 {r4 d'4 r4} e'4 r2.")
>>> auxjad.mutate.contract_notes(staff, abjad.Duration((1, 8)))
ValueError: first positional argument contains one ore more tuplets,
which are not currently supported