aiy.trackplayer

A tracker-based music player for the piezo buzzer.

This API is designed for the Vision Kit, but has no dependency on the Vision Bonnet, so may be used without it. It only requires a piezo buzzer connected to aiy.pins.BUZZER_GPIO_PIN.

class aiy.trackplayer.Arpeggio(*args)

Bases: aiy.trackplayer.Command

Plays an arpeggiated chord.

apply(player, controller, note, tick_delta)

Applies the effect of this command.

classmethod parse(*args)

Parses the arguments to this command into a new command instance.

Returns:A tuple of an instance of this class and how many arguments were consumed from the argument list.

class aiy.trackplayer.Command

Bases: object

Base class for all commands.

apply(player, controller, note, tick_delta)

Applies the effect of this command.

classmethod parse(*args)

Parses the arguments to this command into a new command instance.

Returns:A tuple of an instance of this class and how many arguments were consumed from the argument list.

class aiy.trackplayer.Glissando(direction, hz_per_tick)

Bases: aiy.trackplayer.Command

Pitchbends a note up or down by the given rate.

apply(player, controller, note, tick_delta)

Applies the effect of this command.

classmethod parse(*args)

Parses the arguments to this command into a new command instance.

Returns:A tuple of an instance of this class and how many arguments were consumed from the argument list.

class aiy.trackplayer.JumpToPosition(position)

Bases: aiy.trackplayer.Command

Jumps to the given position in a song.

apply(player, controller, note, tick_delta)

Applies the effect of this command.

classmethod parse(*args)

Parses the arguments to this command into a new command instance.

Returns:A tuple of an instance of this class and how many arguments were consumed from the argument list.

class aiy.trackplayer.NoteOff

Bases: aiy.trackplayer.Command

Stops a given note from playing.

apply(player, controller, note, tick_delta)

Applies the effect of this command.

classmethod parse(*args)

Parses the arguments to this command into a new command instance.

Returns:A tuple of an instance of this class and how many arguments were consumed from the argument list.

class aiy.trackplayer.PulseChange(direction, usec_per_tick)

Bases: aiy.trackplayer.Command

Changes the pulse width of a note up or down by the given rate.

apply(player, controller, note, tick_delta)

Applies the effect of this command.

classmethod parse(*args)

Parses the arguments to this command into a new command instance.

Returns:A tuple of an instance of this class and how many arguments were consumed from the argument list.

class aiy.trackplayer.Retrigger(times)

Bases: aiy.trackplayer.Command

Retriggers a note a consecutive number of times.

apply(player, controller, note, tick_delta)

Applies the effect of this command.

classmethod parse(*args)

Parses the arguments to this command into a new command instance.

Returns:A tuple of an instance of this class and how many arguments were consumed from the argument list.

class aiy.trackplayer.SetPulseWidth(pulse_width_usec)

Bases: aiy.trackplayer.Command

Changes the pulse width of a note up or down by the given rate.

apply(player, controller, note, tick_delta)

Applies the effect of this command.

classmethod parse(*args)

Parses the arguments to this command into a new command instance.

Returns:A tuple of an instance of this class and how many arguments were consumed from the argument list.

class aiy.trackplayer.SetSpeed(speed)

Bases: aiy.trackplayer.Command

Changes the speed of the given song.

apply(player, controller, note, tick_delta)

Applies the effect of this command.

classmethod parse(*args)

Parses the arguments to this command into a new command instance.

Returns:A tuple of an instance of this class and how many arguments were consumed from the argument list.

class aiy.trackplayer.StopPlaying

Bases: aiy.trackplayer.Command

Stops the TrackPlayer from playing.

apply(player, controller, note, tick_delta)

Applies the effect of this command.

classmethod parse(*args)

Parses the arguments to this command into a new command instance.

Returns:A tuple of an instance of this class and how many arguments were consumed from the argument list.

class aiy.trackplayer.TrackLoader(gpio, filename, debug=False)

Bases: object

Simple track module loader.

This class, given a filename and a gpio will load and parse in the given track file and initialize a TrackPlayer instance to play it.

The format of a track file is a plain text file consisting of a header, followed by a number of pattern definitions. Whitespace is ignored in the header and between the patterns.

The header may contain a set of key value pairs like so:

title Some arbitrary song name speed <speed> order <number> [<number>…] end

“title” specifies the title of the song. Optional. This isn’t actually used by the player, but is a nice bit of metadata for humans.

“speed” sets the speed in ticks/row. Optional. The argument, <speed> must be an int. If this isn’t present, the player defaults to a speed of 3.

“order” sets the order of the patterns. It is a single line of space separated integers, starting at 0. Each integer refers to the pattern in order in the file. This keyword must be present.

The keyword “end”, which ends the header.

Patterns take the form:

pattern [E5] [cmnd [<arg>…] …] end

Patterns are started with the “pattern” keyword and end with the “end” keyword. Blank lines inside a pattern are significant – they add time to the song. Any notes that were played continue to play unless they were stopped.

Each row of a pattern consists of a note followed by any number of commands and arguments. A note consists of an upper or lowercase letter A-G (lowercase are sharp notes) and an octave number between 1 and 8. Any time a note appears, it will play only on the first tick, augmented by any commands on the same row. Notes are optional per row.

Commands are four letter lowercase words whose effect is applied every tick. A row may contain nothing but commands, if need be. If the current speed is 3, that means each effect will occur 3 times per row. There may be any number of commands followed by arguments on the same row. Commands available as of this writing are as follows:

glis <direction> <amount-per-tick> puls <direction> <amount-per-tick> spwd <width> arpg [<note>…] vibr <depth> <speed> retg <times> noff sspd <speed> jump <position> stop

glis is a glissando effect, which takes in a <direction> (a positive or negative number) as a direction to go in terms of frequency shift. The <amount-per-tick> value is an integer that is how much of a shift in Hz to apply in the given direction every tick.

puls changes the pulse width of the current PWM waveform in the given <direction> by the <amount-per-tick> in microseconds. <direction> is like <direction> to the glis command.

spwd sets the pulse width of the current PWM waveform directly. <width> is the width of the pulse in microseconds.

arpg performs an arpeggio using the currently playing note and any number of notes listed as arguments. Each note is played sequentially, starting with the currently playing note, every tick. Note that to continue the arpeggio, it will be necessary to list multiple arpg commands in sequence.

vibr performs a vibrato using the currently playing note. The vibrato is applied using the given <depth> in Hz, and the given <speed>.

retg retriggers the note every tick the given number of <times>. This allows for very fast momentary effects when combined with glis, puls, and arpg and high speed values.

noff stops any previously playing note.

sspd sets the current playing speed in <speed> ticks per row.

jump jumps to the given row <position> (offset from the start of the pattern) and continues playing.

stop stops the Player from playing.

COMMANDS = {'arpg': <class 'aiy.trackplayer.Arpeggio'>, 'glis': <class 'aiy.trackplayer.Glissando'>, 'jump': <class 'aiy.trackplayer.JumpToPosition'>, 'noff': <class 'aiy.trackplayer.NoteOff'>, 'puls': <class 'aiy.trackplayer.PulseChange'>, 'retg': <class 'aiy.trackplayer.Retrigger'>, 'spwd': <class 'aiy.trackplayer.SetPulseWidth'>, 'sspd': <class 'aiy.trackplayer.SetSpeed'>, 'stop': <class 'aiy.trackplayer.StopPlaying'>, 'vibr': <class 'aiy.trackplayer.Vibrato'>}

COMMAND_RE = re.compile('(?P<name>[a-z]{4})')

NOTE_RE = re.compile('(?P<name>[A-Ga-g])(?P<octave>[1-8])')

load()

Loads the track module from disk.

Returns:A fully initialized TrackPlayer instance, ready to play.

class aiy.trackplayer.TrackPlayer(gpio, speed=3, debug=False)

Bases: object

Plays a tracker-like song.

add_order(pattern_number)

Adds a pattern index to the order.

add_pattern(pattern)

Adds a new pattern to the player.

Returns:The new pattern index.

play()

Plays the currently configured track.

set_order(position, pattern_number)

Changes a pattern index in the order.

set_position(new_position)

Sets the position inside of the current pattern.

set_speed(new_speed)

Sets the playing speed in ticks/row.

stop()

Stops playing any currently playing track.

class aiy.trackplayer.Vibrato(depth_hz, speed)

Bases: aiy.trackplayer.Command

Vibrates the frequency by the given amount.

apply(player, controller, note, tick_delta)

Applies the effect of this command.

classmethod parse(*args)

Parses the arguments to this command into a new command instance.

Returns:A tuple of an instance of this class and how many arguments were consumed from the argument list.