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 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:

Methods Documentation

SoundEffectorData.__init__(self, v)

Creates a c4d.SoundEffectorData.

Parameters

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

Return type

c4d.SoundEffectorData

Returns

The new SoundEffectorData.

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

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 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

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(float, 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
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

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