Classes > TracksBoard class > Methods > TracksBoard.ItemVolumePointAdd method

Remarks

Predisposes a new volume point on the requested position of the given sound item: the new volume point is not immediately applied so, in order to be effective, new volume points need to be applied through a later call to the TracksBoard.ItemVolumePointsApply method.

Existing volume points can be removed at any time through the TracksBoard.ItemVolumePointRemove method.

This method is disabled and returns an error if the sound duration has been stretched through the TracksBoard.ItemDurationStretch method.

For details about the use of the TracksBoard refer to the How to use the TracksBoard to visually compose songs tutorial.

For further details about methods of the TracksBoard refer to the TracksBoard class section.

Syntax

[Visual Basic]

Public Function ItemVolumePointAdd (

nUniqueId as Int32,

nPositionMs as Int32,

fAmplitude as Single,

strFriendlyName as String

) as enumErrorCodes

[C#]

public enumErrorCodes ItemVolumePointAdd (

Int32 nUniqueId,

Int32 nPositionMs,

float fAmplitude,

string strFriendlyName

);

[C++]

public: enumErrorCodes ItemVolumePointAdd (

Int32 nUniqueId,

Int32 nPositionMs,

float fAmplitude,

string strFriendlyName

);

Parameter

Description

nUniqueId

Unique identification number assigned to the sound item after being generated by one of the following methods:

•	TracksBoard.ItemSoundFileAdd and TracksBoard.ItemSoundFileRawAdd for sound files

•	TracksBoard.ItemSpeechFromStringAdd and TracksBoard.ItemSpeechFromFileAdd for text to speech items

•	TracksBoard.ItemClone when an existing item has been cloned

nPositionMs

Position of the new volume point, expressed in milliseconds, respect to the beginning of the original sound: this position must be within the loaded range set through the nStartPositionMs and nEndPositionMs parameters of the TracksBoard.ItemSoundFileAdd and TracksBoard.ItemSoundFileLoadRangeSet methods or an error would be reported.

This value can be modified at a later time through the TracksBoard.ItemVolumePointPositionSet method or, on the TracksBoard user interface, through mouse interaction.

fAmplitude

Amplitude of the volume point.

Can be a number within the range 0.0 - 2.0; values outside this range will be automatically cut to the nearest accepted value.

- value 0.0 mutes the sound

- values higher than 0.0 and lower than 1.0 attenuate the sound volume

- value 1.0 sets the sound at full volume

- values higher than 1.0 up to 2.0 amplify the sound volume

Setting this value to -1 allows inheriting the same amplitude of the previous volume point.

This value can be modified at a later time through the TracksBoard.ItemVolumePointAmplitudeSet method or, on the TracksBoard user interface, through mouse interaction.

strFriendlyName

String containing the friendly name of the volume point.

This friendly name can be modified at a later time through the TracksBoard.ItemVolumePointFriendlyNameSet method

Return value

Value	Meaning

Negative value	An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0)	The method call was successful.