JSSynth

class psynet.js_synth.ADSRTimbre(attack=0.2, decay=0.1, sustain_amp=0.8, release=0.4)[source]

Bases: Timbre

ADSR timbre base class - not to be instantiated directly.

ADSR is an acronym for ‘Attack, Decay, Sustain, Release’. It is a well-known simple model for the temporal dynamics of an instrument sound.

Parameters:

  • attack (float) – Duration of the ‘attack’ portion of the sound, in seconds.

  • decay (float) – Duration of the ‘decay’ portion of the sound, in seconds.

  • sustain_amp (float) – Amplitude of the ‘sustain’ portion of the sound, in seconds, where ‘1’ corresponds to the maximum amplitude of the sound (as experienced at the transition between the ‘attack’ and ‘decay’ portions).

  • release (float) – Duration of the ‘release’ portion of the sound, in seconds.

class psynet.js_synth.AdditiveTimbre(frequencies, amplitudes, **kwargs)[source]

Bases: ADSRTimbre

Defines an additive timbre. An additive timbre is defined by a collection of frequencies and corresponding amplitudes.

Parameters:

  • frequencies – A list of frequencies, expressed in units of the fundamental frequency.

  • amplitudes – A list of amplitudes, where 1 is typically the amplitude of the fundamental frequency.

  • **kwargs – Extra parameters to pass to ADSRTimbre.

class psynet.js_synth.Chord(pitches, duration='default', silence='default', timbre='default', pan=0.0, volume=1.0)[source]

Bases: dict

A chord is a collection of notes to be played to the user. Chords can be played using the JSSynth control.

Parameters:

  • pitches (List[float]) – A list of pitches to be played, with each pitch expressed as a number on the MIDI scale, where 60 corresponds to middle C (C4) and integer values correspond to semitones.

  • duration (Union[float, str]) – The duration of the chord, in seconds. If left to its default value (“default”), then the chord’s duration will instead be inherited from the default_duration argument provided to JSSynth.

  • silence (Union[float, str]) – The length of silence to have after the chord, in seconds. If left to its default value (“default”), then the chord’s duration will instead be inherited from the default_silence argument provided to JSSynth.

  • timbre (Union[str, List[str]]) –

    The timbre with which to play the chord, specified as a string. There are three different configurations that one can use:

    • Leave both timbre arguments at their default values of "default". In this case the chord will be played with a standard harmonic complex tone.

    • Set the timbre argument in JSSynth to a customized timbre, for example InstrumentTimbre("piano"), while leaving the timbre argument in Chord to its default value. In this case the chord will be played with the customized timbre.

    • Set the timbre argument in JSSynth to a dictionary of customized timbres, and select from this dictionary by specifying an appropriate key in the timbre argument of the Chord object. This provides a way to move between multiple timbres in the same sequence.

    Applying the same logic, one may also pass a list of strings, where each element provides the timbre for a different note in the chord.

  • pan (Union[float, List[float]]) – Optional panning parameter, taking values between -1 (full-left) and +1 (full-right). If this is provided as a list of numbers then these numbers are applied to the respective notes as specified in pitches.

  • volume (float) – Optional volume parameter, taking values between 0 and 1. Passed directly to JSSynth.

class psynet.js_synth.CompressedTimbre(num_harmonics=10, roll_off=12.0, **kwargs)[source]

Bases: ADSRTimbre

This is like the HarmonicTimbre, except with the frequencies compressed slightly, such that the octave corresponds to a frequency ratio of 1.9 rather than 2.0.

Parameters:

  • num_harmonics – Number of harmonics; defaults to 10.

  • roll_off – Roll-off of the harmonic amplitudes in units of dB/octave; defaults to 12.0.

  • **kwargs – Extra parameters to pass to ADSRTimbre.

class psynet.js_synth.HarmonicTimbre(num_harmonics=10, roll_off=12.0, **kwargs)[source]

Bases: ADSRTimbre

Defines a simple harmonic timbre, where all the frequencies are at integer multiples of one another, and the amplitudes decline predictably with increasing harmonic number.

Parameters:

  • num_harmonics – Number of harmonics; defaults to 10.

  • roll_off – Roll-off of the harmonic amplitudes in units of dB/octave; defaults to 12.0.

  • **kwargs – Extra parameters to pass to ADSRTimbre.

class psynet.js_synth.InstrumentTimbre(type, samples=None, base_url='')[source]

Bases: Timbre

Defines an instrument timbre. The timbre is constructed using the Sampler class of Tone.js with samples taken from the MIDI.js Soundfont database (https://github.com/gleitz/midi-js-soundfonts). The Tone.js sampler is provided a note-to-sample dictionary which it then uses to synthesize tones for any required pitch. This is done by pitch-shifting the nearest pitch sample in the dictionary to the desired value, allowing for continuous pitch manipulation. For specific implementation details, see (https://github.com/Tonejs/Tone.js/blob/c313bc6/Tone/instrument/Sampler.ts#L297).

Parameters:

  • type (str) – Instrument to select. This can be drawn from a list of built-in options (see below), alternatively a custom instrument name can be specified, as long as a dictionary of samples is provided to the samples argument.

  • samples (Optional[dict]) – An optional dictionary of samples to use for synthesis. The keys of this dictionary should be note names, for example “F4”, “Gb4”, and so on. The values should be URLs for the sound files.

  • base_url – An optional base_url which is prefixed to the URLs in samples.

class psynet.js_synth.JSSynth(text, sequence, timbre='default', default_duration=0.75, default_silence=0.0, text_align='left')[source]

Bases: Prompt

” JS synthesizer. This uses a Javascript library (‘js-synthesizer’)written by Raja Marjieh, which itself depends heavily on the Tone.JS library. The API for this synthesizer should be considered experimental and potentially subject to change.

The synthesizer allows for playing sequences of arbitrary notes or chords. Only a limited form of polyphony is supported: specifically, the synthesizer can play chords, but all the notes in an individual chord must start and end at the same time.

Note: due to a limitation of the underlying library, performance will suffer drastically if you try and combine Shepard tones with harmonic tones in the same sequence.

Parameters:

  • text – Text to display to the participant. This can either be a string for plain text, or an HTML specification from markupsafe.Markup.

  • sequence – Sequence to play to the participant. This should be a list of objects of class Chord or of class Note.

  • timbre – Optional dictionary of timbres to draw from. The keys of this dictionary should link to the timbre arguments of the Chord/Note objects in sequence. The values should be objects of class Timbre. The default is a harmonic complex tone.

  • default_duration – Default duration of each chord/note in seconds. This may be overridden by specifying the duration argument in the Chord/Note objects.

  • default_silence – Default silence after each chord/note in seconds. This may be overridden by specifying the silence argument in the Chord/Note objects.

  • text_align – CSS alignment of the text (default = "left").

class psynet.js_synth.Note(pitch, **kwargs)[source]

Bases: Chord

A convenience wrapper for Chord where each chord only contains one note. This is useful for writing melodies.

Parameters:

  • pitch (float) – The note’s pitch, expressed as a number on the MIDI scale, where 60 corresponds to middle C (C4) and integer values correspond to semitones.

  • **kwargs – Further options passed to Chord.

class psynet.js_synth.Rest(duration)[source]

Bases: Chord

A convenience wrapper for Chord that defines a rest, i.e., a silence of a specified duration.

Parameters:

duration (Union[float, int]) – Duration of the rest (in seconds).

class psynet.js_synth.ShepardTimbre(num_octave_transpositions=4, shepard_center=65.5, shepard_width=8.2, **kwargs)[source]

Bases: ADSRTimbre

Defines a Shepard tone timbre. Shepard tones are generated by introducing octave transpositions for each of the partials provided in a given additive synthesis. Concretely, each of the specified partials (e.g. in a harmonic complex tone) is augmented by 2 * num_octave_transpositions octaves, positioned symmetrically around each partial frequency. The octave transpositions are weighted using Gaussian weights. By default the Gaussian mean is set to 65.5 semitones and has a standard deviation of 8.2 semitones.

Parameters:

  • num_octave_transpositions – Number of octave transpositions to use in the Shepard synthesis; defaults to 4.

  • shepard_center – The mean of the Gaussian weights used in the Shepard synthesis; defaults to 65.5.

  • shepard_width – The standard deviation of the Gaussian weights used in the Shepard synthesis; defaults to 8.2.

  • **kwargs – Extra parameters to pass to ADSRTimbre.

class psynet.js_synth.StretchedTimbre(num_harmonics=10, roll_off=12.0, **kwargs)[source]

Bases: ADSRTimbre

This is like the HarmonicTimbre, except with the frequencies stretched slightly, such that the octave corresponds to a frequency ratio of 2.0 rather than 1.9.

Parameters:

  • num_harmonics – Number of harmonics; defaults to 10.

  • roll_off – Roll-off of the harmonic amplitudes in units of dB/octave; defaults to 12.0.

  • **kwargs – Extra parameters to pass to ADSRTimbre.

class psynet.js_synth.Timbre[source]

Bases: dict

Timbre base class - not to be instantiated directly.