Plush

SoundCollection#

plupy · Type index

Module: plupy · obtained from plupy.data.sounds

plupy.data.sounds: Sounds imported from .wav files or SoundFont presets, or empty ones to fill with keyzones.

class SoundCollection(DataCollection)

Inherits DataCollection: its members are documented there.

Usage and examples

Members: new · import_file · import_soundfont

new#

new(name: str) -> Sound

An empty Sound with no file, for keyzones (add_zone): a drum kit or a multisample.

A keyzone plays another Sound over the notes keys to to (just keys when to is omitted; every note when both are omitted). pitch=False plays the sample as recorded on every note of the zone (drums); with pitch on it plays from root (default: the sample's own root note). Velocity ranges pick layers by the note's volume; zones with the same nonzero group take turns. A drum kit on the General MIDI notes:

with plupy.edit("Drum kit"):
    kit = plupy.data.sounds.new("Drum kit")
    for name, note in [("Kick", "C-3"), ("Snare", "D-3"), ("Closed hat", "F#3")]:
        kit.add_zone(plupy.data.sounds[name], keys=note, pitch=False)

import_file#

import_file(path: str) -> DataBlock

Copy a .wav into Assets/Sounds and return its Sound datablock (an identical file returns the existing one).

Copies a .wav (8, 16, 24 or 32-bit PCM, or 32-bit float; mono or stereo) into Assets/Sounds and creates a Sound named after the file, with every setting at its default, the same as the editor's Import sound. Importing an identical file returns the existing Sound; an unreadable file raises PlupyError. Settings are props keys sound.volumeDb, sound.group ("Effects", "Music", "Voice", "UI"), sound.loop, sound.rootNote ("C-4"), sound.pitchVariance (± cents), sound.volumeVariance (± dB), sound.startOffset, sound.maxInstances, sound.cooldown, sound.priority, sound.spatialBlend, sound.minDistance, sound.maxDistance and sound.rolloff ("Inverse", "Linear", "Logarithmic"):

with plupy.edit("Footsteps"):
    step = plupy.data.sounds.import_file("Source/step.wav")
    step.props["sound.pitchVariance"] = 40
    step.props["sound.maxInstances"] = 4

Scripts play it with Scene.PlaySound (see Sounds).

import_soundfont#

import_soundfont(path: str, presets: list[tuple[int, int]] | None=None) -> tuple[dict[tuple[int, int], DataBlock], list[str]]

Import a SoundFont 2 (.sf2): every preset, or the (bank, program) pairs listed, as keyzone Sounds shelved in Library > SoundFonts. Presets already imported from the font are reused. Returns ({(bank, program): Sound}, report).

Imports a SoundFont 2 (.sf2): every preset, or the (bank, program) pairs listed (bank 128 holds General MIDI drum kits). Each preset becomes a keyzone Sound shelved in Library → SoundFonts → (font name); its samples become WAVs in Assets/Sounds/SoundFonts/ with their loop points, and each zone's volume envelope a modulation chain on the zone. Presets already imported from the same font are reused. Returns a dict from (bank, program) to the preset's Sound, and a report (its first line counts presets, zones, samples and megabytes; the rest name what was not imported). A compressed .sf3 raises PlupyError. Call it inside plupy.edit:

with plupy.edit("Instruments"):
    presets, report = plupy.data.sounds.import_soundfont("Source/GeneralUser.sf2", presets=[(0, 0), (0, 33), (128, 0)])
    piano = presets[(0, 0)]

DataBlock · DataCollection · Library · PlupyError · Scene · Scripts · Sound · edit

Source#