The SoundEffectorData stores multiple sound probes that are used to sample a given sound file (defined by a sound track). The class also allows to sample the sound file using the defined probes.

The SoundEffectorData class is defined in the customgui_soundeffector.h header file. The data type ID is CUSTOMDATATYPE_SOUNDEFFECTOR. Sub-channel IDs are defined in dsoundprobe.h.

// This example opens a file selection dialog to let the user select a sound file.
// If a file is selected a new Sound Effector using that sound file is added to the
// currently active MoGraph Cloner object.
// check if a Cloner is selected
BaseObject* const moGraphCloner = doc->GetActiveObject();
if (moGraphCloner == nullptr)
return maxon::IllegalArgumentError(MAXON_SOURCE_LOCATION);
if (moGraphCloner->IsInstanceOf(1018544) == false)
return maxon::IllegalArgumentError(MAXON_SOURCE_LOCATION);
// select sound file
Filename soundFile;
if (!soundFile.FileSelect(FILESELECTTYPE::ANYTHING, FILESELECT::LOAD, "Load Sound File"_s))
return maxon::OK;
// create effector
BaseObject* const soundEffector = BaseObject::Alloc(440000255);
if (soundEffector == nullptr)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
// insert sound effector
doc->InsertObject(soundEffector, nullptr, nullptr);
// add effector to the effectors list
GeData clonerData;
InExcludeData* const ieData = static_cast<InExcludeData*>(customData);
if (ieData == nullptr)
return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
ieData->InsertObject(soundEffector, 1 << 0);
// use selected sound file
const DescLevel soundTrackID = DescLevel(CTsound, CTsound, 0);
CTrack* const soundTrack = CTrack::Alloc(soundEffector, soundTrackID);
if (soundTrack == nullptr)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
soundTrack->SetName("New Sound Track"_s);
// set track active sound track
GeData data;
SoundEffectorData* const soundData = static_cast<SoundEffectorData*>(customData);
if (soundData == nullptr)
return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
soundData->SetActiveSoundTrack(soundTrack, doc);
void SetName(const maxon::String &name)
Definition: c4d_baselist.h:2369
void InsertTrackSorted(CTrack *track)
Definition: c4d_baseobject.h:225
static BaseObject * Alloc(Int32 type)
Bool SetParameter(const DescID &id, const GeData &t_data, DESCFLAGS_SET flags)
Bool GetParameter(const DescID &id, GeData &t_data, DESCFLAGS_GET flags)
Bool IsInstanceOf(Int32 id) const
Definition: c4d_baselist.h:1418
Definition: c4d_canimation.h:671
static CTrack * Alloc(BaseList2D *bl, const DescID &id)
Definition: lib_description.h:330
Manages file and path names.
Definition: c4d_file.h:94
Bool FileSelect(FILESELECTTYPE type, FILESELECT flags, const maxon::String &title, const maxon::String &force_suffix=maxon::String())
Definition: c4d_gedata.h:83
CustomDataType * GetCustomDataType(Int32 datatype) const
Definition: c4d_gedata.h:507
InExclude custom data type (CUSTOMDATATYPE_INEXCLUDE_LIST).
Definition: customgui_inexclude.h:115
Bool InsertObject(BaseList2D *pObject, Int32 lFlags)
Definition: customgui_soundeffector.h:147
Bool SetActiveSoundTrack(CTrack *track, BaseDocument *doc)
Definition: ctsound.h:7
InExclude custom data type ID.
Definition: customgui_inexclude.h:25
SoundData ID.
Definition: customgui_soundeffector.h:26
Definition: apibase.h:2818
return OK
Definition: apibase.h:2667
Load dialog.
Any file.
Definition: memoryallocationbase.h:67
#define CTsound
Definition: ge_prepass.h:1513
Definition: obasemogen.h:16
Definition: oesound.h:6
const char * doc
Definition: pyerrors.h:226
Base class for custom data types.
Definition: c4d_customdatatype.h:51
Represents a level within a DescID.
Definition: lib_description.h:289


The SoundEffectorData is typically used with the "Sound" MoGraph effector. An instance of this class is obtained from this object. The parameter ID is defined in oesound.h.

// This example accesses the SoundEffectorData from the given Sound Effector object.
BaseObject* const soundEffector = doc->GetActiveObject();
if (soundEffector == nullptr)
return maxon::IllegalArgumentError(MAXON_SOURCE_LOCATION);
if (soundEffector->IsInstanceOf(440000255) == false)
return maxon::IllegalArgumentError(MAXON_SOURCE_LOCATION);
GeData data;
return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
const SoundEffectorData* const soundData = static_cast<SoundEffectorData*>(customData);
if (soundData == nullptr)
return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
const Int probeCnt = soundData->GetProbeCount();
ApplicationOutput("Sound Effector uses " + String::IntToString(probeCnt) + " probes.");
Int GetProbeCount() const
static String IntToString(Int32 v)
Definition: c4d_string.h:495
maxon::Int Int
Definition: ge_sys_math.h:64
#define ApplicationOutput(formatString,...)
Definition: debugdiagnostics.h:210


A SoundEffectorData object can be created with the usual tools, see Entity Creation and Destruction Manual (Classic).


A SoundEffectorData is referencing a CTrack of the type CTsound. The sound file used in that CTrack is the sound file used by a SoundEffectorData, which is sampled and displayed in the Attribute Manager.

See also CTrack Manual.

// This example gets the file name of the sound file used with the given SoundEffectorData.
// get used sound track
CTrack* const track = soundData->GetActiveSoundTrack(doc);
if (track)
const DescID id = track->GetDescriptionID();
// check if the track is a sound track
if (id[0].id == CTsound)
// get file name
GeData parameterData;
const Filename soundFile = parameterData.GetFilename();
const String soundFileStr = soundFile.GetString();
ApplicationOutput("Sound File: " + soundFileStr);
const DescID & GetDescriptionID() const
Definition: c4d_canimation.h:733
String GetString(void) const
const Filename & GetFilename(void) const
Definition: c4d_gedata.h:475
CTrack * GetActiveSoundTrack(BaseDocument *doc)
Definition: c4d_string.h:39


One or many probes can be used to sample the sound file. Such probes are edited with these functions:

A probe is represented with the Probe class. The "left" and "right" position is defined in Hz, the top and bottom values as a normalized scalar defined between 0.0 and 1.0.

The Probe class also has these public attributes:

// This example adds and configures a new probe.
const Int probeIndex = soundData->CreateProbe();
Probe* const probe = soundData->GetProbe(probeIndex);
if (probe == nullptr)
return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
probe->_samplingMode = 1; // average
probe->_colorMode = 1; // color
probe->_color = Vector { 0.5, 0.5, 1.0 };
Definition: customgui_soundeffector.h:40
Bool SetTop(Float top)
Bool SetRight(Float right)
Vector _color
Color of the probe used when the probe's color mode is Custom Color.
Definition: customgui_soundeffector.h:132
Bool SetBottom(Float bottom)
Int32 _colorMode
The color mode.
Definition: customgui_soundeffector.h:129
Bool SetLeft(Float left)
Int32 _samplingMode
The probe mode.
Definition: customgui_soundeffector.h:130
Int CreateProbe(Float left=1.0, Float right=22050.0, Float top=1.0, Float bottom=0.0, Bool selected=false)
Probe * GetProbe(Int index) const


Additional settings allow to define the range of the frequency spectrum that is currently displayed in the Attribute Manager. These range functions are only valid if the sound data is displayed using the SoundDataCustomGui (e.g. in the Attribute Manager).

Further functions are:

The color used to colorize the sound is defined by a Gradient:

// This example configures the range and changes the global gradient.
soundData->SetRange(1000.0, 2000.0, 0.0, 1.0);
Gradient* const gradient = soundData->GetGradient();
if (gradient == nullptr)
return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
red.pos = 0.0;
red.col = Vector { 1.0, 0, 0 }; // red
GradientKnot green;
green.pos = 1.0;
green.col = Vector { 0.0, 1.0, 0 }; // green
Definition: customgui_gradient.h:150
void FlushKnots()
Flushes all the knots.
Int32 InsertKnot(const GradientKnot &knot)
Gradient * GetGradient() const
void SetGradientDirection(Int32 direction)
void SetRange(Float xmin, Float xmax, Float ymin, Float ymax)
void SetLinLog(Float value)
Represents a knot in a gradient.
Definition: customgui_gradient.h:135
Float pos
Definition: customgui_gradient.h:138
Vector col
Definition: customgui_gradient.h:136


The SoundEffectorData class can be used to sample a sound file. The sound file that is sampled is defined with the active CTrack (see Sound).

The sound data is sampled using the existing probes and their settings.
// This example samples the sound data using the probes and their settings.
if (!soundData->InitSampling(doc))
return maxon::UnknownError(MAXON_SOURCE_LOCATION);
const Int32 sampleCount = 100;
for (Int32 i = 0; i < sampleCount; ++i)
Vector color;
soundData->Sample(i, sampleCount, value, color);
Py_ssize_t i
Definition: abstract.h:645
PyObject * value
Definition: abstract.h:715
Bool InitSampling(BaseDocument *doc)
Bool Sample(Int index, Int count, Float &value, Vector &color)
static String FloatToString(Float32 v, Int32 vvk=-1, Int32 nnk=-3)
Definition: c4d_string.h:529
static String VectorToString(const Vector32 &v, Int32 nnk=-1)
Definition: c4d_string.h:571
maxon::Int32 Int32
Definition: ge_sys_math.h:60
maxon::Float Float
Definition: ge_sys_math.h:66


The settings of a given SoundEffectorData object can be copied with:

Further Reading