NAME

Audio::TinySoundFont::Builder - Construct SoundFont audio by description of play events.

SYNOPSIS

  use Audio::TinySoundFont;
  my $tsf = Audio::TinySoundFont->new('soundfont.sf2');
  my $builder = $tsf->new_builder(
    [
      {
        preset => 'Clarinet',
        note   => 59,
        at     => 0,
        for    => 2,
      },
    ]
  );
  $builder->add(
    [
      {
        preset     => $preset,
        note       => 60,
        at         => 44100,
        for        => 44100 * 2,
        in_seconds => 0,
      },
    ]
  );
  my $samples = $builder->render;

DESCRIPTION

Audio::TinySoundFont::Builder can be used to automate the creation of audio samples by describing the events by what times that notes should be turned on and their duration.

CONSTRUCTOR

Audio::TinySoundFont::Builder is not constructed manually, instead you get an instance from the preset method of Audio::TinySoundFont.

METHODS

soundfont

  my $tsf = $builder->soundfont;

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

play_script

  my $script = $builder->play_script;

The current script that is ready to generate. The play_script is an ArrayRef of HashRefs, each defining a single event. See "add" for details of the events.

NOTE: This structure should only be read, not modified. To make modifications, use "set" or "add".

clear

  $builder->clear;

Clear the play_script.

add

  $builder->add( [ @script_items ] );

Add a list of events to the play_script. Each event HashRef can have the following keys, all other keys will be ignored.

in_seconds

A boolean to indicate if at and for are expressed in seconds or samples. If it is true, which is the default, at and for will be interpreted as seconds.

at

A number that indicates when to trigger the note_on call. If in_seconds is true, this number will be taken as seconds, otherwise it will be number of samples. The default is to start at 0.

for

A number that indicates when to trigger the note_off call. If in_seconds is true, this number will be taken as seconds, otherwise it will be number of samples. The default is to end at 1, which if in_seconds is false, will probably not be what you want.

note

The MIDI note number to activate which will be passed to note_on and note_off. The default is 60, which is Middle C.

vel

The note velocity floating point number between 0.0 and 1.0 that will be passed to note_on. The default is 0.5.

preset

The preset to activate which will be passed to note_on and note_off. It can be a preset name or a Preset object. The default is '', which is likely not what you want because it is unlikely to exist.

set

  $builder->set( [ @script_items ] );

Replaces the play_script with a new list of events. See "add" for the format of the event HashRef.

render =head2 render_unpack

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

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

This method cannot be used if the "soundfont" has any active voices and will croak if that is the case.

volume

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

db

The volume of the sample, expressed in as a logarithmic 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.

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

cpanm Audio::TinySoundFont

perl -MCPAN -e shell
install Audio::TinySoundFont