API REFERENCE

Module jupylet.app

Class App

class jupylet.app.App(width=512, height=512, mode='auto', resource_dir='.', quality=None, **kwargs)

A Jupylet game object.

Parameters:

width (int) – The width of the game canvas in pixels.
height (int) – The height of the game canvas in pixels.
mode (str) – Game mode can be ‘jupyter’ for running the game in a Jupyter notebook, ‘window’ for running the game in a Python script, ‘hidden’ for machine learning, or ‘auto’ for let Jupylet choose the appropriate mode automatically.
resource_dir (path) – A path to the directory of the game assets.
quality (int) – Quality of game video compression specified as an integer between 10 and 100 for when the Jupyter notebook is run on a remote server.

Methods

App.run(interval=0.03333333333333333)

Start the game.

If the game is run in a Jupyter notebook, the call will return immedately with the canvas object on which the game frames will be redrawn, otherwise the call will block until the game is done.

Parameters:: interval (float) – The interval in seconds between frame redraws.
Returns:: The ipywidgets object on which the game will be redrawn.
Return type:: ipywidgets.widgets.widget_media.Image

App.stop(foo=None)

Stop given handler from running. If no handler is given stop the game.

Parameters:: foo (function) – The handler to stop running.

App.set_midi_sound(s)

Start the default MIDI handler with given sound object as its intrument.

Parameters:: s (jupylet.audio.sound.Sound) – The sound object to use as MIDI instrument.

App.observe()

Return game canvas content as upside-down-flipped numpy array.

Returns:: The content of the game canvas an a Numpy array with the shape H x W x 4 corresponding to an RGBA bitmap image.
Return type:: numpy.ndarray

App.scale_window_to(px)

Scale window size so that its biggest dimension (either width or height) is px pixels.

This is useful for RL applications since smaller windows render faster.

Parameters:: px (int) – The target size of the rescaled canvas in pixels.

App.save_state(name, path=None, *args)

Save the state of given game objects to disk.

Parameters:

name (str) – If explicit path is not given, name will be used to automatically generate a filename.
path (str, optional) – An explicit path to use for file.
*args – A list of object implementing the save_state() method, to save to disk.

Returns:

path to saved file.

Return type:

str

App.load_state(path, *args)

Load the state of given game objects from disk.

Will also render the scene once all objects are loaded.

Parameters:

path (str, optional) – An explicit path to use for file.
*args – A list of object implementing the load_state() method, to load from disk.

App.get_logging_widget(height='256px', quiet_default_logger=True)

Returns an output ipywidget to which log messages will be printed.

Returns:: an output ipywidget for log messages.
Return type:: ipywidgets.widgets.widget_output.Output

App.sonic_live_loop2(times=0, **kwargs)

Schedule an async function to run repeatedly in a loop.

The function is scheduled to run based on its name, so updating its definition in a Jupyter notebook will cause the new definition to replace the previous one.

The new definition will kick in once the current iteration through the loop completes.

Parameters:: times (int) – the number of times to run through the loop, or indefinately if 0.

App.sonic_live_loop(times=0, **kwargs)

Schedule an async function to run repeatedly in a loop.

The function is scheduled to run based on its name, so updating its definition in a Jupyter notebook will cause the new definition to replace the previous one.

The new definition will kick in immediately.

Parameters:: times (int) – the number of times to run through the loop, or indefinately if 0.

App.run_me_every(interval, **kwargs)

Schedule a function to run after the specified delay.

The function is scheduled to run based on its name, so updating its definition in a Jupyter notebook will cause the new definition to replace the previous one.

Parameters:: delay (float) – the schedule delay in seconds.

App.run_me(delay=0, **kwargs)

Schedule a function to run after the specified delay.

The function is scheduled to run based on its name, so updating its definition in a Jupyter notebook will cause the new definition to replace the previous one.

Parameters:: delay (float) – the schedule delay in seconds.

App.mouse_position_event(x, y, dx, dy)

App.mouse_press_event(x, y, button)

App.mouse_release_event(x, y, button)

App.key_event(key, action, modifiers)

Handle the on_key event.

Parameters:

key (int) – An integer specifying the key.
action (int) – An integer specifying whether the key was pressed or released.
modifiers (dict) – A dictionary specifying the state the CTRL, ALT, and SHIFT, keys at the time of the event.

App.render(current_time: float, delta: float)

Handle the on_render event.

Parameters:

current_time (float) – Time in seconds since start of game.
delta (float) – Time in seconds since previous call to handler.

App.event(*args): Function decorator for an event handler.

App.close()

Loads a shader program.

Note that path should only be used if all shaders are defined in the same glsl file separated by defines.

If the path is relative the resource system is used expecting one or more resource directories to be registered first. Absolute paths will attempt to load the file directly.

Keyword Arguments:

path (str) – Path to a single glsl file
vertex_shader (str) – Path to vertex shader
geometry_shader (str) – Path to geometry shader
fragment_shader (str) – Path to fragment shader
tess_control_shader (str) – Path to tessellation control shader
tess_evaluation_shader (str) – Path to tessellation eval shader
defines (dict) – #define values to replace in the shader source. Example: {'VALUE1': 10, 'VALUE2': '3.1415'}.
varyings (list[str]) – Out attribute names for transform shaders

Returns:

The program instance

Return type:

moderngl.Program

Properties

App.width

Width of game canvas in pixels.

Type:: bool

App.height

Height of game canvas in pixels.

Type:: bool

Module jupylet.sprite

Class Sprite

class jupylet.sprite.Sprite(img, x=0, y=0, scale=1.0, angle=0.0, anchor_x='center', anchor_y='center', color='white', flip=True, mipmap=True, autocrop=False, anisotropy=8.0, height=None, width=None, name=None, collisions=True)

A 2D game sprite.

Parameters:

img – either a path to a sprite image, a PIL Image object, or a numpy array with image pixel data.
x (float) – The x position for the sprite.
y (float) – The y position for the sprite.
scale (float) – value by which to scale the sprite up or down.
angle (float) – clockwise rotation of the sprite in degrees.
anchor_x (float or str) – either ‘left’, ‘center’ or ‘right’ or a value between 0.0 (for left) and 1.0 (for right) indicating the anchor point inside the sprite along its x axis.
anchor_y (float or str) – either ‘bottom’, ‘center’ or ‘top’ or a value between 0.0 (for bottom) and 1.0 (for top) indicating the anchor point inside the sprite along its y axis.
color (str or 3-tuple) – color by which to tint sprite image. Could be a color name, color hex notation, or a 3-tuple.
flip (bool) – flip the sprite upside down or not.

Methods

Sprite.render(shader=None)

Render sprite to canvas.

Parameters:: shader (moderngl.program.Program, optional) – OpenGL shader program to use for rendering.

Sprite.draw(shader=None): Render sprite to canvas - this is an alias to Sprite.render().

Sprite.set_anchor(ax=None, ay=None)

Set the anchor point of the sprite.

The anchor is a point in the sprite that is used for rotation and positioning. Imagine a pin going through the sprite and that you use this pin to position the sprite on the canvas and to rotate it. The point at which the pin goes through the texture is the anchor point.

The anchor point is set separately for the x axis, and for the y axis.

Parameters:

ax (str or float) – the x anchor can be one of ‘left’, ‘center’, ‘right’, or a float value between 0.0 (left) and 1.0 (right).
ay (str or float) – the y anchor can be one of ‘bottom’, ‘center’, ‘top’, or a float value between 0.0 (bottom) and 1.0 (top).

Sprite.collisions_with(o, debug=False)

Compute collisions with given sprite.

Parameters:: o (Sprite) – The other sprite with which to check collisions.
Returns:: An 2d array with collision points or an empty array if sprites do not collide.
Return type:: numpy.ndarray

Sprite.distance_to(o=None, pos=None)

Compute the distance to another sprite or coordinate.

Parameters:

o (Sprite, optional) – Other sprite to compute distance to.
pos (tuple, optional) – An (x, y) coordinate to compute distance to.

Returns:

Distance in pixels.

Return type:

float

Sprite.angle_to(o=None, pos=None)

Compute clockwise angle in degrees to another sprite or coordinate.

Parameters:

o (Sprite, optional) – Other sprite to compute angle to.
pos (tuple, optional) – An (x, y) coordinate to compute angle to.

Returns:

Angle in degrees.

Return type:

float

Sprite.wrap_position(width, height, margin=50)

Wrap sprite’s coordinates around given canvas width and height.

Use this method to make the sprite come back from one side of the canvas if it goes out from the opposite side.

Parameters:

width (float) – The canvas width to wrap around.
height (float) – The canvas height to wrap around.
margin (float, optional) – An extra margin to add around canvas before wrapping the sprite around to the opposite side.

Sprite.clip_position(width, height, margin=0)

Clip sprite’s coordinates to given canvas width and height.

Use this method to prevent the sprite from going out of the canvas.

Parameters:

width (float) – The canvas width to clip to.
height (float) – The canvas height to clip to.
margin (float, optional) – An extra margin to add around canvas before clipping the sprite’s coordinates.

Sprite.get_state()

Get a dictionary of properties defining the object state.

Returns:: A dictionary of properties.
Return type:: dict

Sprite.set_state(s)

Set object state from given dictionary of properties.

Parameters:: s (dict) – A dictionary of properties previously returned by a call to get_state().

Properties

Sprite.scale

Scale of sprite.

The scale equals the rendered width in pixels divided by the actual width of the texture. E.g a scale of 2 will make the sprite appear twice as big than it originally is, and a scale of 1/2 twice as small.

Type:: float

Sprite.x

The x coordinate of the anchor position.

Type:: float

Sprite.y

The y coordinate of anchor position.

Type:: float

Sprite.angle

The rotation angle around the anchor in degrees.

Type:: float

Sprite.width

Width in pixels after scaling.

Type:: float

Sprite.height

Height in pixels after scaling.

Type:: float

Sprite.image

Bitmap image of sprite.

You can set this property with a new image or with a path to an image on disk to change the current sprite image.

Type:: PIL.Image.Image

Sprite.top

Get the top coordinate of the sprite’s bounding box.

Type:: float

Sprite.right

Get the right coordinate of the sprite’s bounding box.

Type:: float

Sprite.bottom

Get the bottom coordinate of the sprite’s bounding box.

Type:: float

Sprite.left

Get the left coordinate of the sprite’s bounding box.

Type:: float

Sprite.radius

Get the radius of a circle containing the sprite’s bounding box.

Type:: float

Sprite.opacity

Get or set the opacity of the sprite.

Setting opacity to 0 would render the sprite completely transparent. Settint opacity to 1 would render the sprite completely opaque.

Type:: float

Sprite.color

Get or set the color of the sprite.

The sprite color will be multiplied by the color values of its bitmap image.

The color can be specified by name (e.g. ‘white’) or in hex notation (e.g ‘#cc4488’) or as a 4-tuple or glm.vec4 value.

Type:: glm.vec4

Sprite.flip=True

Flip the image upside down while rendering.

Type:: bool

Sprite.mipmap=True

Compute mipmap textures when first loading the sprite image.

Type:: bool

Sprite.autocrop=False

Auto crop the image to its bounding box when first loading the sprite image.

Type:: bool

Sprite.anisotropy=8.0

Use anisotropic filtering when rendering the sprite image.

Type:: float

Module jupylet.label

Class Label

class jupylet.label.Label(text='', font_path='fonts/SourceSerifPro-Bold.otf', font_size=16, line_height=1.2, align='left', bold=False, italic=False, color='white', x=0, y=0, angle=0.0, width=None, height=None, anchor_x='left', anchor_y='baseline')

A text label.

Since a text label is actually implemented as a 2D sprite, it has all the functionality and methods of a Sprite.

Parameters:

text (str) – text to render as label.
font (path) – path to a true type or open type font.
font_size (float) – font size to use.
line_height (float) – determines the distance between lines.
align (str) – the desired alignment for the text label. May be one of ‘left’, ‘center’, and ‘right’.
color (str or 3-tuple) – a color name, color hex notation, or a 3-tuple. specifying the color for the text label.
x (float) – the x position for the label.
y (float) – the y position for the label.
angle (float) – clockwise rotation of the label in degrees.
anchor_x (float or str) – either ‘left’, ‘center’ or ‘right’ or a value between 0.0 (for left) and 1.0 (for right) indicating the anchor point inside the label along its x axis.
anchor_y (float or str) – either ‘bottom’, ‘baseline’, ‘center’ or ‘top’ or a value between 0.0 (for bottom) and 1.0 (for top) indicating the anchor point inside the label along its y axis.

Properties

Label.text

Text to render as label.

Type:: str

Label.font_path

Path to a true type or open type font.

Type:: str

Label.font_size=16

Font size to use.

Type:: float

Label.line_height=1.2

Determines the distance between lines.

Type:: float

Label.align='left'

The desired alignment for the text label. May be one of ‘left’, ‘center’, and ‘right’.

Type:: str

Module jupylet.loader

jupylet.loader.load_blender_gltf(path)

Load a Blender scene or model exported with the Blender glTF 2.0 exporter.

The Blender scene should be exported using the glTF Separate (.gltf + .bin + textures) format. In the exporter make sure to check the Apply Modifiers, UVs, and Normals, options checkboxes.

Note that in principle this function should be able to load any gltf 2.0 scene, however it was only tested with and tuned to load scenes exported with Blender 2.83 and Blender 3.4.

Parameters:: path (str) – path to glTF 2.0 file.
Returns:: A scene object.
Return type:: Scene

Module jupylet.model

Class Scene

class jupylet.model.Scene(name, shadows=False)

A 3D Scene object.

While it is possible to create a Scene object manually, it is probably a better idea to call jupylet.loader.load_blender_gltf() instead.

Methods

Scene.draw(shader=None)

Render scene to canvas.

Parameters:: shader (moderngl.program.Program, optional) – OpenGL shader program to use for rendering.

Properties

Scene.meshes

A list of meshes.

Type:: list

Scene.lights

A list of lights.

Type:: list

Scene.cameras

A list of cameras.

Type:: list

Scene.materials

A list of materials.

Type:: list

Scene.skybox

A Skybox object.

Type:: Skybox

Scene.shadows

Set to True to enable shadows.

Type:: bool

Scene.name

Name of scene.

Type:: str

Class Mesh

class jupylet.model.Mesh(name, rotation=None, scale=None, position=None, parent=None)

A 3D Mesh object.

While it is possible to create a Mesh object manually, it is probably a better idea to call jupylet.loader.load_blender_gltf() instead.

Methods

Mesh.move_local(xyz)

Move by given displacement in local coordinate system.

Parameters:: xyz (glm.vec3) – Displacement.

Mesh.move_global(xyz)

Move by given displacement in global coordinate system.

Parameters:: xyz (glm.vec3) – Displacement.

Mesh.rotate_local(angle, axis=(0.0, 0.0, 1.0))

Rotate counter clockwise by given angle around given axis in local coordinate system.

Parameters:

angle (float) – Angle in radians.
axis (glm.vec3) – Rotation axis.

Mesh.rotate_global(angle, axis=(0.0, 0.0, 1.0))

Rotate counter clockwise by given angle around given axis in global coordinate system.

Parameters:

angle (float) – Angle in radians.
axis (glm.vec3) – Rotation axis.

Properties

Mesh.front

Return the local front (+z) axis.

Type:: glm.vec3

Mesh.up

Return the local up (+y) axis.

Type:: glm.vec3

Mesh.primitives

List of primitives the mesh consists of.

Type:: list

Mesh.children

List of child meshes.

Type:: list

Mesh.hide

Set to False to hide mesh from view.

Type:: bool

Mesh.name

Name of mesh.

Type:: str

Module jupylet.audio

jupylet.audio.sonic_py(resource_dir='.')

Start an audio application.

An audio application is need to run live loops.

Parameters:: resource_dir (str) – Path to root of resource dir, for samples, etc…
Returns:: A running application object.
Return type:: App

jupylet.audio.set_bpm(bpm=240)

Set the tempo to the given beats per minute.

Parameters:: bpm (float) – Beats per minute.

jupylet.audio.set_note_value(v=4)

Set the note value representing one beat.

Parameters:: v (float) – Note value.

jupylet.audio.use(sound, **kwargs)

Set the instrument to use in subsequent calls to play().

You can supply key/value pairs of properties to modify in the given instrument. If you do, the instrument will be copied first, and the modifications will be applied to the new copy.

Parameters:

sound (GatedSound) – Instrument to use.
**kwargs – Properties of intrument to modify.

jupylet.audio.play(note, duration=None, **kwargs)

Play given note polyphonically with the instrument previously set by call to use().

You can supply key/value pairs of properties to modify in the given instrument.

Parameters:

note (float) – Note to play in units of semitones where 60 is middle C.
duration (float, optional) – Duration to play note, in whole notes.
**kwargs – Properties of intrument to modify.

jupylet.audio.sleep(duration=0)

Get some sleep.

Example

@app.sonic_live_loop2
async def boom_pam():

    use(tb303, resonance=8, decay=1/8, cutoff=48, amp=1)

    play(C2, 1/8)
    await sleep(1/4)

    play(C3, 1/8)
    await sleep(1/4)

Parameters:: duration (float) – Duration to sleep in whole notes.
Returns:: A sleep coroutine to use with await.
Return type:: coroutine

Module jupylet.audio.sound

Class Sound

class jupylet.audio.sound.Sound(freq=261.63, amp=0.5, pan=0.0, shared=False)

The base class for all other sound classes, including audio samples, oscillators and effects.

The Jupylet Sound class is the basic element for defining a sound processing computational graph, as a hierarchy of sound classes; e.g, a synthesizer containing a reverb effect containing an allpass filter.

Audio building blocks and components such as oscillators, effects, etc…, typically inherit from the Sound class, while instruments such as synthesizers should typically inherit the GatedSound class.

Parameters:

freq (float) – Default frequency.
amp (float) – Output amplitude - a value between 0 and 1.
pan (float) – Balance between left (-1) and right (1) output channels.
shared (bool) – Designate sound object as shared by multiple other sound instances.

Methods

Sound.play(note=None, **kwargs)

Play given note monophonically.

If sound is already playing, it will be reset.

Parameters:

note (float) – Note to play in units of semitones where 60 is middle C.
**kwargs – Properties of intrument to modify.

Sound.play_poly(note=None, **kwargs)

Play given note polyphonically.

This function will play note on a new copy of self. If sound is already playing, the new note will join it.

Parameters:

note (float) – Note to play in units of semitones where 60 is middle C.
**kwargs – Properties of intrument to modify.

Returns:

The sound object representing the newly playing note.

Return type:

Sound

Sound.play_release(stop=True, **kwargs): Stop playing sound and all of its polyphonic copies.

Sound.set_effects(*effects)

Set effects to be applied to the output of this sound instance.

Parameters:: *effects – Sound effects instances.

Sound.get_effects()

Get list of effects for this sound object.

Returns:: A (possibly empty) list of sound effects.
Return type:: list

Properties

Sound.note

Get note closest to current sound frequency, as a string.

Type:: str

Sound.key

Get current sound frequency in semitone units where 60 is middle C.

Type:: float

Sound.freq

Fundamental requency of sound object.

Type:: float

Sound.amp

Output amplitude - a value between 0 and 1.

Type:: float

Sound.pan

Balance between left (-1) and right (1) output channels.

Type:: float

Class Oscillator

class jupylet.audio.sound.Oscillator(shape='sine', freq=261.63, key=None, phase=0.0, sign=1, duty=0.5, **kwargs)

Waveform generator for sine, triangle, anti-aliased sawtooth, and variable duty anti-aliased square waveforms.

Parameters:

shape (str) – Waveform to generate - one of sine, triangle, sawtooth, or square.
freq (float) – Fundamental frequency of generator.
key (float, optional) – Fundamental frequency of generator in semitone units where middle C is 60.
sign (float) – Set to -1 to flip sawtooth waveform upside down.
duty (float) – The fraction of the square waveform cycle its value is 1.

Note

An Oscillator inherits all the methods and properties of a Sound class.

Methods

Oscillator.forward(key_modulation=None, sign=None, duty=None, **kwargs)

Properties

Oscillator.shape

Waveform to generate - one of sine, triangle, sawtooth, or square.

Type:: str

Oscillator.sign

Set to -1 to flip sawtooth waveform upside down.

Type:: float

Oscillator.duty

The fraction of the square waveform cycle its value is 1.

Type:: float

Class LatencyGate

class jupylet.audio.sound.LatencyGate

A synthesizer on/off gate.

A synthesizer gate outputs an on/off signal that is used to trigger signal processing such as envelope generators etc…

This particular latency gate is designed to schedule on and off transitions using system time to enable triggering notes with precise timing despite fluctuations in the latency of the operating system.

Methods

LatencyGate.open(t=None, dt=None, **kwargs)

Schedule gate open at specified time.

The schedule can be an absolute time given by the argument t, or a delta dt after the schedule of the latest event already scheduled.

Parameters:

t (float, optional) – Time in seconds since epoch, as returned by Python’s standard library time.time().
dt (float, optional) – Time in seconds after the current last scheduled event.

LatencyGate.close(t=None, dt=None, **kwargs)

Schedule gate close at specified time.

The schedule can be an absolute time given by the argument t, or a delta dt after the schedule of the latest event already scheduled.

Parameters:

t (float, optional) – Time in seconds since epoch, as returned by Python’s standard library time.time().
dt (float, optional) – Time in seconds after the current last scheduled event.

Class GatedSound

class jupylet.audio.sound.GatedSound(freq=261.63, amp=0.5, pan=0.0, duration=None)

A sound class capable of precise timing and duration of notes.

Parameters:

freq (float) – Fundamental frequency.
amp (float) – Output amplitude - a value between 0 and 1.
pan (float) – Balance between left (-1) and right (1) output channels.
duration (float, optional) – Duration to play note, in whole notes.

Methods

GatedSound.play(note=None, duration=None, **kwargs)

Play given note monophonically.

If sound is already playing, it will be reset.

Parameters:

note (float) – Note to play in units of semitones where 60 is middle C.
duration (float, optional) – Duration to play note, in whole notes.
**kwargs – Properties of intrument to modify.

GatedSound.play_poly(note=None, duration=None, **kwargs)

Play given note polyphonically.

This function will play note on a new copy of self. If sound is already playing, the new note will join it.

Parameters:

note (float) – Note to play in units of semitones where 60 is middle C.
duration (float, optional) – Duration to play note, in whole notes.
**kwargs – Properties of intrument to modify.

Returns:

The sound object representing the newly playing note.

Return type:

GatedSound

GatedSound.play_release(stop=False, **kwargs): Stop playing sound and all of its polyphonic copies.

Module jupylet.audio.sample

Class Sample

class jupylet.audio.sample.Sample(path, freq=261.63, key=None, loop=False, amp=0.5, pan=0.0, duration=None)

A class to play audio files and samples.

The Sample class can play audio files of type WAV, OGG, or FLAC, and it can also play basic SFZ format multi sampled virtual instruments. If a sample of a virtual instrument includes markers for a loop segment, the loop argument will cause the sample to loop around its loop segment.

Parameters:

path (str) – Path to audio file.
freq (float) – Fundamental frequency.
key (float, optional) – Fundamental frequency of generator in semitone units where middle C is 60.
loop (str) – Loop sample back to its beginning.
amp (float) – Output amplitude - a value between 0 and 1.
pan (float) – Balance between left (-1) and right (1) output channels.
duration (float, optional) – Duration to play note, in whole notes.

Methods

Sample.load()

Load specified sample file into memory.

Returns:: self
Return type:: Sample

Properties

Sample.path

Path to audio file.

Type:: str