Quantization

Written music on a page has notes of exact lengths and start times, but live performance of music is always a little imprecise; that is, in part, what makes a live performance feel live.

Most early computer-music formats required that notes start and end on exact time intervals. Many popular music genres today also use exact notes and rhythms.

The process of converting live-performance or inexact to exact start times and durations is called quantization.

Much of the processing that ChiptuneSAK uses to modify, display, and convert between music formats requires quantized music. ChiptuneSAK uses unique algorithms to quantize music and also provides the ability to de-quantize music output to some formats.

ChiptuneSAK Quantization

If the desired quantization is known a priori, ChiptuneSAK will quantize note starts and durations to known parameters.

For source material where note starts and durations are close to exact note lengths, but are noisy, and/or the minimum note length is not known, ChiptuneSAK provides an algorithm that automatically finds and applies the optimum quantization.

Note: The ChiptuneSAK quantization functions are only meant for music where the quarter-note length is known and the note start times and durations are close to the quantized values. For source material where the note lengths and time offsets are not known well (such as in most midi rips of game music), ChiptuneSAK provides other tools to help adjust the music to the point where quantization can be used.

Base Quantization Functions

All the quantization functions are applied in the Chirp Representation of the music.

The base quantization functions that encapsulate the algorithm and perform the quantization are:

chiptunesak.chirp.find_quantization(time_series, ppq)

Find the optimal quantization in ticks to use for a given set of times. The algorithm given here is by no means universal or guaranteed, but it usually gives a sensible answer.

The algorithm works as follows: - Starting with quarter notes, obtain the error from quantization of the entire set of times. - Then obtain the error from quantization by 2/3 that value (i.e. triplets). - Then go to the next power of two (e.g. 8th notes, a6th notes, etc.) and repeat

A minimum in quantization error will be observed at the “right” quantization. In either case above, the next quantization tested will be incommensurate (either a factor of 2/3 or a factor of 3/4) which will make the quantization error worse.

Thus, the first minimum that appears will be the correct value.

The algorithm does not seem to work as well for note durations as it does for note starts, probably because performed music rarely has clean note cutoffs.

Parameters:

• time_series (list of int) – a series times, usually note start times, in ticks
• ppq (int) – ppq value (ticks per quarter note)

Returns:

quantization in ticks

Return type:

int

chiptunesak.chirp.find_duration_quantization(durations, qticks_note)

The duration quantization is determined from the shortest note length. The algorithm starts from the estimated quantization for note starts.

Parameters:

• durations (list of int) – durations from which to estimate quantization
• qticks_note (int) – quantization already determined for note start times

Returns:

estimated duration quantization, in ticks

Return type:

int

chiptunesak.chirp.quantize_fn(t, qticks)

This function quantizes a time or duration to a certain number of ticks. It snaps to the nearest quantized value.

Parameters:

• t (int) – a start time or duration, in ticks
• qticks (int) – quantization in ticks

Returns:

quantized start time or duration

Return type:

int

Quantization Methods

Primary use of the quantization algorithms occurs through methods of the ChirpSong and ChirpTrack classes.

ChirpSong.estimate_quantization()

This method estimates the optimal quantization for note starts and durations from the note data itself. This version all note data in the tracks. Many pieces have no discernable duration quantization, so in that case the default is half the note start quantization. These values are easily overridden.

ChirpSong.quantize(qticks_notes=None, qticks_durations=None)

This method applies quantization to both note start times and note durations. If you want either to remain unquantized, simply specify a qticks parameter to be 1 (quantization of 1 tick).

Parameters:

• qticks_notes (int) – Quantization for note starts, in MIDI ticks
• qticks_durations (int) – Quantization for note durations, in MIDI ticks

ChirpSong.quantize_from_note_name(min_note_duration_string, dotted_allowed=False, triplets_allowed=False)

Quantize song with more user-friendly input than ticks. Allowed quantizations are the keys for the constants.DURATION_STR dictionary. If an input contains a ‘.’ or a ‘-3’ the corresponding values for dotted_allowed and triplets_allowed will be overridden.

Parameters:

• min_note_duration_string (str) – Quantization note value
• dotted_allowed (bool) – If true, dotted notes are allowed
• triplets_allowed (bool) – If true, triplets (of the specified quantization) are allowed

ChirpTrack.estimate_quantization()

This method estimates the optimal quantization for note starts and durations from the note data itself. This version only uses the current track for the optimization. If the track is a part with long notes or not much movement, I recommend using the get_quantization() on the entire song instead. Many pieces have fairly well-defined note start spacing, but no discernable duration quantization, so in that case the default is half the note start quantization. These values are easily overridden.

Returns:tuple of quantization values for (start, duration) Return type:tuple of ints

ChirpTrack.quantize(qticks_notes=None, qticks_durations=None)

This method applies quantization to both note start times and note durations. If you want either to remain unquantized, simply specify either qticks parameter to be 1, so that it will quantize to the nearest tick (i.e. leave everything unchanged)

Parameters:

• qticks_notes (int) – Resolution of note starts in ticks
• qticks_durations (int) – Resolution of note durations in ticks. Also length of shortest note.