pytakt.timemap module

This module defines classes for retrieving tempo values and time signatures in a score and for converting between ticks, seconds, bar numbers, and beat numbers.

current_tempo() → float

Returns the current tempo.

Returns:

Tempo value (beats per minute)

set_tempo(bpm) → None

Changes the current tempo.

Parameters:

bpm (float) – Tempo value (beats per minute)

class TempoMap(score, default_tempo=125.0)

Bases: object

This class represents a data structure (tempo map) in which tempo events are extracted from the score. Tempo maps can be used to obtain tempo values at arbitrary time and to convert between ticks (480ths of a quarter note) and seconds.

Constructor

Parameters:

  • score (Score) – Target score (infinite-length score allowed)

  • default_tempo (float) – If there is a section at the beginning of the score with no tempo events, the tempo for that section is assumed to be this value.


tempo_at(ticks) → Union[int, float]

Returns the tempo at ticks from the beginning of the score.

Parameters:

ticks (ticks) – Ticks from the beginning of the score.

Returns:

Tempo value (BPM)

ticks2sec(ticks) → float

Converts ticks from the beginning of the score to seconds.

Parameters:

ticks (ticks) – Ticks from the beginning of the score

Returns:

Seconds from the beginning of the score

sec2ticks(seconds) → Union[int, float, Fraction]

Converts seconds from the beginning of the score to ticks.

Parameters:

seconds (float) – Seconds from the beginning of the score

Returns:

Ticks from the beginning of the score

class TimeSignatureMap(score, bar0len=None)

Bases: object

This class represents a data structure (time signature map) in which time signature events are extracted from the score. This can be used to obtain time signature at arbitrary time or to convert between ticks and measure/beat numbers.

If there are no time-signature events, the score is assumed to be in 4/4 time.

The measure (bar) number starts from 0 if there is a special measure (“Bar 0”) at the beginning due to Auftakt, etc., otherwise it starts from 1. The first measure number can be obtained with ticks2mbt(0)[0].

Constructor

Parameters:

  • score (Score) – Target score (infinite-length score allowed)

  • bar0len (ticks, optional) – Specifies the length of Bar 0. If 0 is specified, it means that the score does not have Bar 0. If it is None, the length is inferred from the positions of the time signature events.


timesig_at(ticks) → TimeSignatureEvent

Returns the time signature as of ticks from the beginning of the score.

Parameters:

ticks (ticks) – Ticks from the beginning of the score.

Returns:

A time signature event. The attribute ‘default’ is added for the 4/4 time signature event compensated for scores with no indication of time signature.

num_measures() → int

Returns the total number of measures in the score; not available for EventStream.

ticks2mbt(ticks) → Tuple[int, Union[int, float, Fraction], int, Union[int, float, Fraction]]

Converts ticks from the beginning of the score to a 4-element tuple of (measure number, ticks within the measure, beat number, ticks within the beat).

Parameters:

ticks (ticks) – Ticks from the beginning of the score

Returns:

The first element represents the measure number. The second element represents ticks within the measure. The third element represents the beat number in the measure, starting from 0. The last element represents ticks within the beat. The length of a beat depends on the time signature (e.g., in 3/8 time, it is an eighth note (i.e., 240 ticks)).

mbt2ticks(measures, beats=0, ticks=0) → Union[int, float, Fraction]

Given the measure number, the beat number, and additional ticks, it finds ticks from the beginning of the score.

Parameters:

  • measures (int or str) – a measure number or a string of the form “measures`[:`beats][+ticks]” (“[]” means optional). If beats or ticks is specified in the string, the corresponding argument values show below are invalid. If a non-existent beat number is specified in the string, an exception is raised.

  • beats (int or float, optional) – The number of beats in the measure, starting from 0. The length of a beat depends on the time signature.

  • ticks (ticks, optional) – Ticks to be added, which may be longer than one beat.

Returns:

Ticks from the beginning of the score.

iterator() → Generator[Union[int, float, Fraction], None, Union[int, float, Fraction]]

A generator function that yields the start time of each measure in order.

Yields:

ticks – The start time of each measure

Raises:

StopIteration – Raised when the end of the score is reached. The ‘value’ attribute of this exception object contains the duration of the score.

class TimeMap(score, default_tempo=125.0, bar0len=None)

Bases: TempoMap, TimeSignatureMap

This class integrates the TempoMap and TimeSignatureMap classes. If both functionalites are needed for a single score, it is more efficient to use this class because it requires only one score traversal.

Constructor

Parameters:

  • score (Score) – Target score (infinite-length score allowed)

  • default_tempo (float) – If there is a section at the beginning of the score with no tempo events, the tempo for that section is assumed to be this value.

  • bar0len (ticks, optional) – Specifies the length of Bar 0. If 0 is specified, it means that the score does not have Bar 0. If it is None, the length is inferred from the positions of the time signature events.


iterator() → Generator[Union[int, float, Fraction], None, Union[int, float, Fraction]]

A generator function that yields the start time of each measure in order.

Yields:

ticks – The start time of each measure

Raises:

StopIteration – Raised when the end of the score is reached. The ‘value’ attribute of this exception object contains the duration of the score.

mbt2ticks(measures, beats=0, ticks=0) → Union[int, float, Fraction]

Given the measure number, the beat number, and additional ticks, it finds ticks from the beginning of the score.

Parameters:

  • measures (int or str) – a measure number or a string of the form “measures`[:`beats][+ticks]” (“[]” means optional). If beats or ticks is specified in the string, the corresponding argument values show below are invalid. If a non-existent beat number is specified in the string, an exception is raised.

  • beats (int or float, optional) – The number of beats in the measure, starting from 0. The length of a beat depends on the time signature.

  • ticks (ticks, optional) – Ticks to be added, which may be longer than one beat.

Returns:

Ticks from the beginning of the score.

num_measures() → int

Returns the total number of measures in the score; not available for EventStream.

sec2ticks(seconds) → Union[int, float, Fraction]

Converts seconds from the beginning of the score to ticks.

Parameters:

seconds (float) – Seconds from the beginning of the score

Returns:

Ticks from the beginning of the score

tempo_at(ticks) → Union[int, float]

Returns the tempo at ticks from the beginning of the score.

Parameters:

ticks (ticks) – Ticks from the beginning of the score.

Returns:

Tempo value (BPM)

ticks2mbt(ticks) → Tuple[int, Union[int, float, Fraction], int, Union[int, float, Fraction]]

Converts ticks from the beginning of the score to a 4-element tuple of (measure number, ticks within the measure, beat number, ticks within the beat).

Parameters:

ticks (ticks) – Ticks from the beginning of the score

Returns:

The first element represents the measure number. The second element represents ticks within the measure. The third element represents the beat number in the measure, starting from 0. The last element represents ticks within the beat. The length of a beat depends on the time signature (e.g., in 3/8 time, it is an eighth note (i.e., 240 ticks)).

ticks2sec(ticks) → float

Converts ticks from the beginning of the score to seconds.

Parameters:

ticks (ticks) – Ticks from the beginning of the score

Returns:

Seconds from the beginning of the score

timesig_at(ticks) → TimeSignatureEvent

Returns the time signature as of ticks from the beginning of the score.

Parameters:

ticks (ticks) – Ticks from the beginning of the score.

Returns:

A time signature event. The attribute ‘default’ is added for the 4/4 time signature event compensated for scores with no indication of time signature.

class KeySignatureMap(score)

Bases: object

Class for a data structure (key signature map) that extracts key signature events from a score. This is used to obtain the key at any given time.

If there is no key signature event, the key is assumed to be C major.

Constructor

Parameters:

score (Score) – Target score (infinite-length score allowed)


key_at(ticks, tk=0) → Key

Returns the key at ticks from the beginning of the score.

Parameters:

  • ticks (ticks) – Ticks from the beginning of the score.

  • tk (int) – Specifies the track number. If there are any key signature events on this track, they are used to determine the key. If not, the key is determined based on the key signature events in Track 0.