The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Audio-TinySoundFont-0.12
River stage zero No dependents
++
/ Audio::TinySoundFont::Preset

NAME

Audio::TinySoundFont::Preset - SoundFont Preset Represntation

SYNOPSIS

  use Audio::TinySoundFont;
  my $preset = $tsf->preset('Clarinet');
  my $audio  = $preset->render(seconds => 5, note => 59, vel => 0.7, volume => .3);

DESCRIPTION

Audio::TinySoundFont::Preset is a Preset, or musical sample in the SoundFont nomenclature. It is the largest usable building block in a SoundFont and generally represents a single instrument.

CONSTRUCTOR

Audio::TinySoundFont::Preset is not constructed manually, instead you get an instance from the preset or preset_index methods of Audio::TinySoundFont.

METHODS

soundfont

The Audio::TinySoundFont object that this Preset object was created from.

index

The index of this preset in the SoundFont file.

name

The name of the preset. For example, it could be "Clarinet", "Accordion", "Standard Drums" or "Sine Wave".

render

  my $samples = $preset->render(%options);

Returns a string of 16-bit, little endian sound samples for this preset using TinySoundFont. The result can be unpacked using unpack("s<*") or you can call "render_unpack" function to get an array instead. It accepts several options that allow you to customize how the sound should be generated.

This method cannot be used if the "soundfont" is currently playing anything and will croak if that is the case.

options

seconds

This sets how long the preset should be played for, from Attack to Release. It defaults to 1 second. If both "seconds" and "samples" are given, seconds will be used.

NOTE: The sample is not constrained to the number of seconds given, it is the minimum number of seconds that will be returned. The sound may continue to play after these many seconds, and often will, because of the decay phase of the SoundFont.

samples

This is an alternative way to set how long the preset should be played for, from Attack to Release, measure in 16-bit samples. It defaults to 1 second worth of samples. If both "seconds" and "samples" are given, seconds will be used.

NOTE: The sample is not constrained to the number of samples given, it is the minimum number of samples that will be returned. The sound may continue to play after these many samples, and often will, because of the decay phase of the SoundFont.

note

This is the MIDI note to be played with 60 meaning middle C, which is the default. It is an integer between 0 and 127.

vel

The MIDI velocity of the note played, expressed as a float between 0 and 1, the default is 0.5. Generally a velocity causes a louder noise to be played, but the SoundFont can use it modify other aspects of the sound. This is separate from "volume" which controls the general volume of the resulting sample.

volume

The general volume of the sample, expressed as a float between 0 and 1. If both "volume" and "db" are given, volume will be used.

db

The volume of the sample, expressed in as a dB float between -100 and 0, with -100 being equivalent to silent and 0 being as loud as TinySoundFont can go. If both "volume" and "db" are given, volume will be used.

render_unpack

  my @samples = $preset->render_unpack(%options);

Returns an array of of 16-bit sound samples for this preset using TinySoundFont. All of the options are identical to "render".

AUTHOR

Jon Gentle <cpan@atrodo.org>

COPYRIGHT

Copyright 2020- Jon Gentle

LICENSE

This is free software. You may redistribute copies of it under the terms of the Artistic License 2 as published by The Perl Foundation.

SEE ALSO

Audio::TinySoundFont, TinySoundFont.