Methods > Playlists > PlayListItemVolAutomPointAdd method

Remarks

Adds a new volume point to an item of the playlist.

This method will return an error if the playlist has not been created with the PlayListCreateEx method or loaded with the PlayListLoad or PlayListLoadSync methods, all having the nMode parameter set to PLAYLIST_AUTOMATION_MODE.

For further details about playlists management see the How to create and manage a playlist tutorial.

For details about using Volume Automation refer to the How to manage Volume Automation tutorial.

Syntax

[Visual Basic]

Public Function PlayListItemVolAutomPointAdd (

nPlayerIndex as Int16,

nItemIndex as Int16,

strVolumePointName as String,

nPositionUnit as enumVolumeAutomationPosUnits,

fPosition as Single,

nVolumeScaleType as enumVolumeScales,

fVolumeLevel as Single,

nCurveType as enumVolumeCurves,

nDesignerUniqueId as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes PlayListItemVolAutomPointAdd (

Int16 nPlayerIndex,

Int16 nItemIndex,

string strVolumePointName,

enumVolumeAutomationPosUnits nPositionUnit,

float fPosition,

enumVolumeScales nVolumeScaleType,

float fVolumeLevel,

enumVolumeCurves nCurveType,

Int32 nDesignerUniqueId

);

[C++]

public: enumErrorCodes PlayListItemVolAutomPointAdd (

Int16 nPlayerIndex,

Int16 nItemIndex,

string strVolumePointName,

enumVolumeAutomationPosUnits nPositionUnit,

float fPosition,

enumVolumeScales nVolumeScaleType,

float fVolumeLevel,

enumVolumeCurves nCurveType,

Int32 nDesignerUniqueId

);

Parameter

Description

nPlayerIndex

Number representing the zero-based index of the involved player

nItemIndex

Number representing the zero-based index of the item inside the playlist. The number of available items can be obtained using the PlayListGetCount method.

strVolumePointName

String representing the friendly name of the volume point to add: there is no naming convention so you are free to decide your own set of names. This name will be used in next calls that will act on this specific volume point.

nPositionUnit

The unit used to define positions of volume points.

Supported values are the following:

Mnemonic constant	Value	Meaning
VA_POS_UNIT_SECONDS	0	Positions are expressed in seconds
VA_POS_UNIT_PERCENTAGE	1	Positions are expressed in percentage
VA_POS_UNIT_MILLISECONDS	2	Positions are expressed in milliseconds

fPosition

Position of the volume point expressed in the same unit set into the nPositionUnit parameter.

nVolumeScaleType

The volume scaling type.

Supported values are the following:

Mnemonic constant

Value

Meaning

SCALE_LINEAR

The returned volume is based upon a linear scale and can be in the range from 0.0 (silence) to 100.0 (max volume)

SCALE_LOG

The returned volume, expressed in dB, is based upon a logarithmic scale and can be in the range from -100 (silence) to 0 (max volume)

The actual applied formula for converting a linear volume into a logarithmic volume is the following:

VolumeInDB = 20 * log10 (VolumeLinear/100)

The C syntax for converting a logarithmic volume into a linear volume is the following:

VolumeLinear = 100 * pow (10, VolumeInDB/20);

fVolumeLevel

Volume level expressed in the same unit set into the nVolumeScaleType parameter

nCurveType

Type of curve applied to reach the next volume point.

Supported values are the following:

Mnemonic constant	Value	Meaning

VOLUME_CURVE_NONE	0	No curve is applied: volume will be changed immediately and will be kept till next volume point.
VOLUME_CURVE_LINEAR	1	Linear curve
VOLUME_CURVE_EXPONENTIAL	2	Exponential curve
VOLUME_CURVE_COSINE	3	Cosine curve
VOLUME_CURVE_SMOOTH	4	Smooth curve
VOLUME_CURVE_CUSTOM	5	Custom Bézier curve.

nDesignerUniqueId

Unique identifier of the curve editor control containing custom curve settings to apply. This unique identifier is returned by a previous call to the VolumeAutomation.CurveDesigner.Create method.

The custom curve designer manages a windowed control, whose visual aspect can be defined programmatically, which allows designing volume curves based upon Bézier curves whose shape is defined through the manual positioning of 2 control points (displayed in cyan color on the graphic below). For further information about the use of the embedded CurveDesigner refer to the tutorial How to create custom volume curves.

Return value

Value	Meaning

enumErrorCodes.NOERROR (0)	The method call was successful
Negative value	An error occurred: see the LastError property for further error details or for a list of the possible error values.