c4d.SoundEffectorData¶

class c4d.SoundEffectorData¶: Sound effector data type (CUSTOMDATATYPE_SOUNDEFFECTOR) for SoundEffectorCustomGui.

New in version R19.

Methods Signatures

SoundEffectorData.__init__(self, v)

Creates a c4d.SoundEffectorData.

`SoundEffectorData.CreateProbe(self, left, right, top, ...)`	Creates a probe.
`SoundEffectorData.GetProbeCount(self)`	Retrieves the number of probes owned by the sound effector data.
`SoundEffectorData.GetProbe(self, index)`	Retrieves the probe at the specified index.
`SoundEffectorData.SetProbe(self, index, probe)`	Sets the probe at the specified index.
`SoundEffectorData.DeleteProbe(self, index)`	Deletes the probe at the specified index.
`SoundEffectorData.UpdateProbeOrder(self)`	Updates the probes.
`SoundEffectorData.GetRange(self)`	Retrieves the range of the sound effector data.
`SoundEffectorData.SetRange(self, left, right, top, ...)`	Sets the range of the sound effector data.
`SoundEffectorData.GetLinLog(self)`	Retrieves the blend value for the linear/logarithmic slider.
`SoundEffectorData.SetLinLog(self, value)`	Sets the blend value for the linear/logarithmic slider.
`SoundEffectorData.GetFreeze(self)`	Retrieves the freeze state.
`SoundEffectorData.SetFreeze(self, freeze)`	Sets the freeze state.
`SoundEffectorData.GetGradient(self)`	Retrieves the global gradient.
`SoundEffectorData.GetGradientDirection(self)`	Retrieves the global gradient direction.
`SoundEffectorData.SetGradientDirection(self, direction)`	Sets the global gradient direction.
`SoundEffectorData.InitSampling(self, doc)`	Initializes the sampling functionality of the sound effector data.
`SoundEffectorData.FreeSampling(self)`	Frees the memory used for sampling.
`SoundEffectorData.Sample(self, index, count)`	Samples the sound file using the probes.
`SoundEffectorData.SetActiveSoundTrack(self, track, doc)`	Sets the active sound track.
`SoundEffectorData.GetActiveSoundTrack(self, doc)`	Retrieves the active sound track.
`SoundEffectorData.CopyTo(self, dest)`	Copies the sound effector data.

Inheritance

Parent Class:

c4d.CustomDataType

Methods Documentation

SoundEffectorData.__init__(self, v)¶

Creates a c4d.SoundEffectorData.

Parameters: v (c4d.SoundEffectorData) – An optional c4d.SoundEffectorData to copy.

SoundEffectorData.CreateProbe(self, left, right, top, bottom, selected=False)¶

Creates a probe.

Parameters

left (float) – The left side of the probe in Hertz [1,22050].
right (float) – The right side of the probe in Hertz [1,22050].
top (float) – The top edge of the probe in the range [0,1].
bottom (float) – The bottom edge of the probe in the range [0,1].
selected (bool) – True to select the created probe. Other probes are not deselected in the operation.

Return type

int

Returns

The created probe’s index.

SoundEffectorData.GetProbeCount(self)¶

Retrieves the number of probes owned by the sound effector data.

Return type: int
Returns: The probe count.

SoundEffectorData.GetProbe(self, index)¶

Retrieves the probe at the specified index.

Parameters

index (int) – The probe index.

Return type

Optional[dict]

Returns

The probe, or None if the function fails. The dictionary contains the following data:

left	float	The left value of probe in Hertz.
right	float	The right value of probe in Hertz.
top	float	The top value of probe in Hertz.
bottom	float	The bottom value of probe in Hertz.
strength	float	The overall strength multiplier for the probe.
clamp	bool	True limits the output of the probe from 0.0 to 1.0 and ignores values outside of the range.
samplingMode	int	The probe mode.
colorMode	int	The color mode.
color	`c4d.Vector`	The color of the probe used when colorMode is Custom Color.
gradient	`c4d.Gradient`	The gradient of the probe used when colorMode is Custom Gradient.

SoundEffectorData.SetProbe(self, index, probe)¶

Sets the probe at the specified index.

Parameters

index (int) – The index of the probe to set.

probe (dict) –

The probe data to set:

left	float	The left value of probe in Hertz.
right	float	The right value of probe in Hertz.
top	float	The top value of probe in Hertz.
bottom	float	The bottom value of probe in Hertz.
strength	float	The overall strength multiplier for the probe.
clamp	bool	Set to True to limit the output of the probe from 0.0 to 1.0 and to ignore values outside of the range.
samplingMode	int	The probe mode.
colorMode	int	The color mode.
color	`c4d.Vector`	The color of the probe used when colorMode is Custom Color.
gradient	`c4d.Gradient`	The gradient of the probe used when colorMode is Custom Gradient.

SoundEffectorData.DeleteProbe(self, index)¶

Deletes the probe at the specified index.

Parameters: index (int) – The index of the probe to delete.
Return type: bool
Returns: True if successful, otherwise False.

SoundEffectorData.UpdateProbeOrder(self)¶: Updates the probes.

Note

Must be called after adjusting any probes left or right values to update the order that the probes are calculated in.

SoundEffectorData.GetRange(self)¶

Retrieves the range of the sound effector data.

Warning

Only valid if the data is shown in the sound sound effector GUI.

Return type: Tuple[float, float, float, float]
Returns: A tuple with the left, right, top and bottom values.

SoundEffectorData.SetRange(self, left, right, top, bottom)¶

Sets the range of the sound effector data.

Warning

Only valid if the data is shown in the sound effector GUI.

Parameters

left (float) – The left value to set.
right (float) – The right value to set.
top (float) – The top value to set.
bottom (float) – The bottom value to set.

SoundEffectorData.GetLinLog(self)¶

Retrieves the blend value for the linear/logarithmic slider.

Return type: float
Returns: The blend percentage: 0% = linear, 100% = log10.

SoundEffectorData.SetLinLog(self, value)¶

Sets the blend value for the linear/logarithmic slider.

Parameters: value (float) – The blend percentage to set: 0% = linear, 100% = log10.

SoundEffectorData.GetFreeze(self)¶

Retrieves the freeze state.

Return type: bool
Returns: True if freeze is enabled, otherwise False.

SoundEffectorData.SetFreeze(self, freeze)¶

Sets the freeze state.

Parameters: freeze (bool) – True to enable freeze, otherwise False.

SoundEffectorData.GetGradient(self)¶

Retrieves the global gradient.

Return type: Optional[c4d.Gradient]
Returns: The global gradient, or None if the function fails.

SoundEffectorData.GetGradientDirection(self)¶

Retrieves the global gradient direction.

Return type: int
Returns: The global gradient direction: 0 for vertical (volume), 1 for horizontal (frequency).

SoundEffectorData.SetGradientDirection(self, direction)¶

Sets the global gradient direction.

Parameters: direction (int) – The global gradient direction to set: 0 for vertical (volume), 1 for horizontal (frequency).

SoundEffectorData.InitSampling(self, doc)¶

Initializes the sampling functionality of the sound effector data.

Note

Must be called before Sample(). FreeSampling() must be invoked afterwards.

Parameters: doc (c4d.documents.BaseDocument) – The document for the operation.
Return type: bool
Returns: True if successful, otherwise False.

SoundEffectorData.FreeSampling(self)¶

Frees the memory used for sampling.

Note

Must be invoked after InitSampling() has been called.

Return type: bool
Returns: True if successful, otherwise False.

SoundEffectorData.Sample(self, index, count)¶

Samples the sound file using the probes.

Parameters

index (int) – The index of the element to sample.
count (int) – The number of elements in the array being sampled.

Return type

Tuple[Optional[float], Optional[c4d.Vector]]

Returns

A tuple with the output value and color (both None if the function failed).

SoundEffectorData.SetActiveSoundTrack(self, track, doc)¶

Sets the active sound track.

Parameters

track (c4d.CTrack) – The sound track to set.
doc (c4d.documents.BaseDocument) – The document for the operation.

Return type

bool

Returns

True if successful, otherwise False.

SoundEffectorData.GetActiveSoundTrack(self, doc)¶

Retrieves the active sound track.

Parameters: doc (c4d.documents.BaseDocument) – The document for the operation.
Return type: Optional[c4d.CTrack]
Returns: The active sound track, or None if the function fails.

SoundEffectorData.CopyTo(self, dest)¶

Copies the sound effector data.

Parameters: dest (c4d.SoundEffectorData) – The destination sound effector data.
Return type: bool
Returns: True if successful, otherwise False