NAME

Audio::Hydrogen::Instrument - represent a hydrogen instrument

DESCRIPTION

Instruments are found primarily in Audio::Hydrogen::Drumkit object from where they are used in songs. An instrument comprises at least one audio sample in WAV or FLAC format with various settings that may change the way it sounds. Most of the attributes have reasonable defaults.

METHODS

attribute id

This is required and must be unique in either a drumkit or song where it is used, typically it is in the range 0 - 31. If you are copying individual instruments from different drumkits into a song you may need to change the id so that they remain unique.

The id is referenced in the patterns of a song so you probably don't want to change it after any patterns have been created (unless of course you actually want to change the played instrument.)

attribute name

This is the free text name of the instrument, it must be set if the instrument is to be usable in the Hydrogen interface as the absence of a name may be taken as being an "empty instrument".

attribute filename

This is the name of the sample file that should be either a WAV or FLAC format, if used in a drumkit it may be relative to the drumkit directory, if the instrument is being used in a song then this should be an absolute path.

If this is empty then there is expected to be one or more layer specified as described below.

attribute volume

This is the volume of the instrument a Rat in the range 0 .. 1.0 The default is 1.0

attribute is-muted

This is a boolean to indicate whether the instrument is muted, typically not used in a drumkit but may be used in a song.

attribute is-locked

If this bool is set, the instrument settings can't be changed in the interface.

attribute pan-left

This is a Rat in the range 0 .. 1.0 to indicate the panning to the left side.

attribute pan-right

This is a Rat in the range 0 .. 1.0 to indicate the panning to the right side.

attribute random-pitch-factor

This is a Rat in the range 0 .. 1.0 that appears to indicate a range of variation of the playback speed of the sample, the default is 0.0

attribute gain

This is a gain factor in the range 0 .. 1.0 that is applied to the sample. The default is 1.

attribute filter-active

This is a boolean to indicate whether the low pass filter is engaged, the default is False.

attribute filter-cutoff

This is a Rat in the range 0 .. 1.0 that indicates the filter cutoff frequency, 0 is the lowest cutoff which effectively doesn't pass anything and 1.0 sounds like it passes everything.

attribute filter-resonance

This is a Rat in the range 0 .. 1.0 that indicates the low pass filter resonance (i.e. gain applied around the filter cutoff frequency or feedback,) it is a more marked effect in the middle range of cutoff frequency.

attribute attack

This is the length of time that is taken for the sample to be played at full volume, the default is 0, obviously some values may be longer than the sample length and it won't be played at all.

attribute decay

This is the length of time taken after the attack part for the level to go to the sustain level, the default is 0.

attribute sustain

This is the level at which the sustained part of the sample is played, the default is 1 (i.e. full volume.)

attribute release

This is the length of time the sample takes for the volume to reduce to 0, the default is 1000. The net result of the default settings for the envelope is that the sample is played verbatim.

attribute exclude

I've never seen a file with this in and don't know what it is. If you know please let me know.

attribute layer

This is a list of Audio::Hydrogen::Instrument::Layer objects, these provide a way of specifying different samples to be used depending on the velocity of a note in a pattern. If this is empty then filename must be specified, (or vice versa.)

The Audio::Hydrogen::Instrument::Layer class has the following attributes:

attribute filename

This is the filename of a FLAC or WAV sample that will be played for this layer, if this being used in a drumkit it can be relative to the drumkit directory, if used in a song it should be an absolute path.

attribute min

This is the minimum velocity that this layer should be used for, it is a Rat in the range of 0 .. 1.0,

attribute max

This is the maximum velocity that this layer should be used for, it is a Rat in the range of 0 .. 1.0

attribute gain

The gain factor to be applied to the sample for this layer.

attribute pitch

The pitch that the sample should be played back at for this layer.

method make-absolute

This method should be called on the instrument when it is being copied from a drumkit to a song. It takes an IO::Path that should be the directory containing the drumkit and will make the sample filenames explicitly children of that path.