--- name: "SoVRMLAudioClip" section: "3" platform: "linux" package: "coin" version: "1:4.0.10-1" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/SoVRMLAudioClip" --- # SoVRMLAudioClip(3) The SoVRMLAudioClip class is used to load and store audio data. ## NAME SoVRMLAudioClip - The **SoVRMLAudioClip** class is used to load and store audio data. ## SYNOPSIS \#include \ Inherits **SoNode**. ### Public Types typedef void \* **open\_func**(const **SbStringList** &**url**, **SoVRMLAudioClip** \*clip, void \*userdataptr)\ typedef size\_t **read\_func**(void \*datasource, void \*buffer, int numframes, int &channels, **SoVRMLAudioClip** \*clip, void \*userdataptr)\ typedef int **seek\_func**(void \*datasource, long offset, int whence, **SoVRMLAudioClip** \*clip, void \*userdataptr)\ typedef long **tell\_func**(void \*datasource, **SoVRMLAudioClip** \*clip, void \*userdataptr)\ typedef int **close\_func**(void \*datasource, **SoVRMLAudioClip** \*clip, void \*userdataptr)\ Public Types inherited from **SoNode** enum **NodeType** { **INVENTOR** = 0x0000, **VRML1** = 0x0001, **VRML2** = 0x0002, **INVENTOR\_1** = 0x0004, **INVENTOR\_2\_0** = 0x0008, **INVENTOR\_2\_1** = 0x0010, **INVENTOR\_2\_5** = 0x0020, **INVENTOR\_2\_6** = 0x0040, **COIN\_1\_0** = 0x0080, **COIN\_2\_0** = 0x0100, **EXTENSION** = 0x0200, **COIN\_2\_2** = 0x0400, **COIN\_2\_3** = 0x0800, **COIN\_2\_4** = 0x1000, **INVENTOR\_5\_0** = 0x2000, **COIN\_2\_5** = 0x4000, **COIN\_3\_0** = 0x8000, **INVENTOR\_6\_0** = 0x10000, **COIN\_4\_0** = 0x20000 }\ ### Public Member Functions virtual **SoType** **getTypeId** (void) const\ **SoVRMLAudioClip** (void)\ int **getSampleRate** ()\ void \* **open** (const **SbStringList** &**url**)\ size\_t **read** (void \*datasource, void \*buffer, int numframes, int &channels)\ int **seek** (void \*datasource, long offset, int whence)\ long **tell** (void \*datasource)\ int **close** (void \*datasource)\ void **setCallbacks** (open\_func \*opencb, read\_func \*readcb, seek\_func \*seekcb, tell\_func \*tellcb, close\_func \*closecb, void \*userdataptr)\ Public Member Functions inherited from **SoNode** void **setOverride** (const SbBool state)\ SbBool **isOverride** (void) const\ void **setNodeType** (const **NodeType** type)\ **NodeType** **getNodeType** (void) const\ virtual **SoNode** \* **copy** (SbBool copyconnections=FALSE) const\ virtual SbBool **affectsState** (void) const\ virtual void **doAction** (**SoAction** \*action)\ virtual void **GLRender** (**SoGLRenderAction** \*action)\ virtual void **GLRenderBelowPath** (**SoGLRenderAction** \*action)\ virtual void **GLRenderInPath** (**SoGLRenderAction** \*action)\ virtual void **GLRenderOffPath** (**SoGLRenderAction** \*action)\ virtual void **callback** (**SoCallbackAction** \*action)\ virtual void **getBoundingBox** (**SoGetBoundingBoxAction** \*action)\ virtual void **getMatrix** (**SoGetMatrixAction** \*action)\ virtual void **handleEvent** (**SoHandleEventAction** \*action)\ virtual void **pick** (**SoPickAction** \*action)\ virtual void **rayPick** (**SoRayPickAction** \*action)\ virtual void **search** (**SoSearchAction** \*action)\ virtual void **write** (**SoWriteAction** \*action)\ virtual void **audioRender** (**SoAudioRenderAction** \*action)\ virtual void **getPrimitiveCount** (**SoGetPrimitiveCountAction** \*action)\ virtual void **grabEventsSetup** (void)\ virtual void **grabEventsCleanup** (void)\ virtual void **startNotify** (void)\ virtual void **notify** (**SoNotList** \*l)\ SbUniqueId **getNodeId** (void) const\ virtual **SoChildList** \* **getChildren** (void) const\ virtual void **writeInstance** (**SoOutput** \*out)\ virtual **SoNode** \* **addToCopyDict** (void) const\ virtual void **copyContents** (const **SoFieldContainer** \*from, SbBool copyconnections)\ virtual **SoFieldContainer** \* **copyThroughConnection** (void) const\ Public Member Functions inherited from **SoFieldContainer** void **setToDefaults** (void)\ SbBool **hasDefaultValues** (void) const\ SbBool **fieldsAreEqual** (const **SoFieldContainer** \*container) const\ void **copyFieldValues** (const **SoFieldContainer** \*container, SbBool copyconnections=FALSE)\ SbBool **set** (const char \*const fielddata)\ void **get** (**SbString** &fielddata)\ virtual int **getFields** (**SoFieldList** &l) const\ virtual int **getAllFields** (**SoFieldList** &l) const\ virtual **SoField** \* **getField** (const **SbName** &name) const\ virtual **SoField** \* **getEventIn** (const **SbName** &name) const\ virtual **SoField** \* **getEventOut** (const **SbName** &name) const\ SbBool **getFieldName** (const **SoField** \*const field, **SbName** &name) const\ SbBool **enableNotify** (const SbBool flag)\ SbBool **isNotifyEnabled** (void) const\ SbBool **set** (const char \*fielddata, **SoInput** \*input)\ void **get** (**SbString** &fielddata, **SoOutput** \*out)\ virtual SbBool **validateNewFieldValue** (**SoField** \*field, void \*newval)\ virtual void **addWriteReference** (**SoOutput** \*out, SbBool isfromfield=FALSE)\ SbBool **getIsBuiltIn** (void) const\ virtual void **getFieldsMemorySize** (size\_t &managed, size\_t &unmanaged) const\ void **setUserData** (void \*userdata) const\ void \* **getUserData** (void) const\ Public Member Functions inherited from **SoBase** void **ref** (void) const\ void **unref** (void) const\ void **unrefNoDelete** (void) const\ int32\_t **getRefCount** (void) const\ void **touch** (void)\ SbBool **isOfType** (**SoType** type) const\ Returns TRUE if the type of this object is either of the same type or inherited from *type*. virtual **SbName** **getName** (void) const\ virtual void **setName** (const **SbName** &newname)\ void **addAuditor** (void \*const auditor, const **SoNotRec::Type** type)\ void **removeAuditor** (void \*const auditor, const **SoNotRec::Type** type)\ const **SoAuditorList** & **getAuditors** (void) const\ SbBool **shouldWrite** (void)\ void **assertAlive** (void) const\ ### Static Public Member Functions static **SoType** **getClassTypeId** (void)\ static void **initClass** (void)\ static void **setSubdirectories** (const **SbList**\< **SbString** \> &subdirectories)\ static const **SbStringList** & **getSubdirectories** ()\ static void **setDefaultPauseBetweenTracks** (**SbTime** pause)\ static **SbTime** **getDefaultPauseBetweenTracks** ()\ static void **setDefaultIntroPause** (**SbTime** pause)\ static **SbTime** **getDefaultIntroPause** ()\ static void **setDefaultSampleRate** (int samplerate)\ static int **getDefaultSampleRate** ()\ static void **setDefaultTimerInterval** (**SbTime** interval)\ static **SbTime** **getDefaultTimerInterval** ()\ Static Public Member Functions inherited from **SoNode** static uint32\_t **getCompatibilityTypes** (const **SoType** &nodetype)\ static **SoType** **getClassTypeId** (void)\ static **SoNode** \* **getByName** (const **SbName** &name)\ static int **getByName** (const **SbName** &name, **SoNodeList** &l)\ static void **initClass** (void)\ Sets up initialization for data common to all instances of this class, like submitting necessary information to the Coin type system. static void **initClasses** (void)\ static SbUniqueId **getNextNodeId** (void)\ static int **getActionMethodIndex** (const **SoType** type)\ static void **getBoundingBoxS** (**SoAction** \*action, **SoNode** \*node)\ static void **GLRenderS** (**SoAction** \*action, **SoNode** \*node)\ static void **callbackS** (**SoAction** \*action, **SoNode** \*node)\ static void **getMatrixS** (**SoAction** \*action, **SoNode** \*node)\ static void **handleEventS** (**SoAction** \*action, **SoNode** \*node)\ static void **pickS** (**SoAction** \*action, **SoNode** \*node)\ static void **rayPickS** (**SoAction** \*action, **SoNode** \*node)\ static void **searchS** (**SoAction** \*action, **SoNode** \*node)\ static void **writeS** (**SoAction** \*action, **SoNode** \*node)\ static void **audioRenderS** (**SoAction** \*action, **SoNode** \*node)\ static void **getPrimitiveCountS** (**SoAction** \*action, **SoNode** \*node)\ Static Public Member Functions inherited from **SoFieldContainer** static void **initClass** (void)\ Sets up initialization for data common to all instances of this class, like submitting necessary information to the Coin type system. static **SoType** **getClassTypeId** (void)\ This static method returns the **SoType** object associated with objects of this class. static void **cleanupClass** (void)\ static void **initCopyDict** (void)\ static void **addCopy** (const **SoFieldContainer** \*orig, const **SoFieldContainer** \*copy)\ static **SoFieldContainer** \* **checkCopy** (const **SoFieldContainer** \*orig)\ static **SoFieldContainer** \* **findCopy** (const **SoFieldContainer** \*orig, const SbBool copyconnections)\ static void **copyDone** (void)\ Static Public Member Functions inherited from **SoBase** static void **initClass** (void)\ Sets up initialization for data common to all instances of this class, like submitting necessary information to the Coin type system. static **SoType** **getClassTypeId** (void)\ This static method returns the **SoType** object associated with objects of this class. static void **addName** (**SoBase** \*const base, const char \*const name)\ static void **removeName** (**SoBase** \*const base, const char \*const name)\ static void **incrementCurrentWriteCounter** (void)\ static void **decrementCurrentWriteCounter** (void)\ static **SoBase** \* **getNamedBase** (const **SbName** &name, **SoType** type)\ static int **getNamedBases** (const **SbName** &name, **SoBaseList** &baselist, **SoType** type)\ static SbBool **read** (**SoInput** \*input, **SoBase** \*&base, **SoType** expectedtype)\ static void **setInstancePrefix** (const **SbString** &c)\ static void **setTraceRefs** (SbBool trace)\ static SbBool **getTraceRefs** (void)\ static SbBool **connectRoute** (**SoInput** \*input, const **SbName** &fromnodename, const **SbName** &fromfieldname, const **SbName** &tonodename, const **SbName** &tofieldname)\ static SbBool **readRoute** (**SoInput** \*input)\ ### Public Attributes **SoSFString** **description**\ **SoSFBool** **loop**\ **SoSFFloat** **pitch**\ **SoSFTime** **startTime**\ **SoSFTime** **stopTime**\ **SoMFString** **url**\ ### Protected Member Functions virtual const **SoFieldData** \* **getFieldData** (void) const\ virtual **~SoVRMLAudioClip** ()\ Protected Member Functions inherited from **SoNode** **SoNode** (void)\ virtual **~SoNode** ()\ virtual SbBool **readInstance** (**SoInput** \*in, unsigned short flags)\ Protected Member Functions inherited from **SoFieldContainer** **SoFieldContainer** (void)\ virtual **~SoFieldContainer** ()\ Protected Member Functions inherited from **SoBase** **SoBase** (void)\ virtual **~SoBase** ()\ virtual void **destroy** (void)\ SbBool **hasMultipleWriteRefs** (void) const\ SbBool **writeHeader** (**SoOutput** \*out, SbBool isgroup, SbBool isengine) const\ void **writeFooter** (**SoOutput** \*out) const\ virtual const char \* **getFileFormatName** (void) const\ virtual **SoNotRec** **createNotRec** (void)\ ### Static Protected Member Functions static const **SoFieldData** \*\* **getFieldDataPtr** (void)\ Static Protected Member Functions inherited from **SoNode** static const **SoFieldData** \*\* **getFieldDataPtr** (void)\ static void **setNextActionMethodIndex** (int index)\ static int **getNextActionMethodIndex** (void)\ static void **incNextActionMethodIndex** (void)\ static void **setCompatibilityTypes** (const **SoType** &nodetype, const uint32\_t bitmask)\ Static Protected Member Functions inherited from **SoBase** static uint32\_t **getCurrentWriteCounter** (void)\ static void **staticDataLock** (void)\ static void **staticDataUnlock** (void)\ ### Protected Attributes **SoSFTime** **duration\_changed**\ **SoSFBool** **isActive**\ Protected Attributes inherited from **SoNode** SbUniqueId **uniqueId**\ Protected Attributes inherited from **SoFieldContainer** SbBool **isBuiltIn**\ ### Additional Inherited Members Protected Types inherited from **SoBase** enum **BaseFlags** { **IS\_ENGINE** = 0x01, **IS\_GROUP** = 0x02 }\ Static Protected Attributes inherited from **SoNode** static SbUniqueId **nextUniqueId** = 1\ static int **nextActionMethodIndex** = 0\ ## Detailed Description The **SoVRMLAudioClip** class is used to load and store audio data. Audio data is loaded using the simage library, so make sure you have built the simage library with support for the audio file formats you intend to use (libogg, libvorbis and libvorbisfile for OggVorbis, libsndfile for WAV and several other formats). **The detailed class documentation is taken verbatim from the VRML97 standard (ISO/IEC 14772-1:1997). It is copyright The Web3D Consortium, and is used by permission of the Consortium:**\ ``` AudioClip { exposedField SFString description "" exposedField SFBool loop FALSE exposedField SFFloat pitch 1.0 # (0, inf) exposedField SFTime startTime 0 # (-inf, inf) exposedField SFTime stopTime 0 # (-inf, inf) exposedField MFString url [] eventOut SFTime duration_changed eventOut SFBool isActive } ``` An AudioClip node specifies audio data that can be referenced by Sound nodes. The description field specifies a textual description of the audio source. A browser is not required to display the description field but may choose to do so in addition to playing the sound. The url field specifies the URL from which the sound is loaded. Browsers shall support at least the wavefile format in uncompressed PCM format (see http://www.web3d.org/documents/specifications/14772/V2.0/part1/bibliography.html#\[WAV\]). It is recommended that browsers also support the MIDI file type 1 sound format (see http://www.web3d.org/documents/specifications/14772/V2.0/part1/references.html#\[MIDI\]); MIDI files are presumed to use the General MIDI patch set. Subclause 4.5, VRML and the World Wide Web (http://www.web3d.org/documents/specifications/14772/V2.0/part1/concepts.html#4.5), contains details on the url field. The results are undefined when no URLs refer to supported data types. The loop, startTime, and stopTime exposedFields and the isActive eventOut, and their effects on the AudioClip node, are discussed in detail in 4.6.9, Time-dependent nodes (http://www.web3d.org/documents/specifications/14772/V2.0/part1/concepts.html#4.6.9). The "cycle" of an AudioClip is the length of time in seconds for one playing of the audio at the specified pitch. The pitch field specifies a multiplier for the rate at which sampled sound is played. Values for the pitch field shall be greater than zero. Changing the pitch field affects both the pitch and playback speed of a sound. A set\_pitch event to an active AudioClip is ignored and no pitch\_changed eventOut is generated. If pitch is set to 2.0, the sound shall be played one octave higher than normal and played twice as fast. For a sampled sound, the pitch field alters the sampling rate at which the sound is played. The proper implementation of pitch control for MIDI (or other note sequence sound clips) is to multiply the tempo of the playback by the pitch value and adjust the MIDI Coarse Tune and Fine Tune controls to achieve the proper pitch change. A duration\_changed event is sent whenever there is a new value for the "normal" duration of the clip. Typically, this will only occur when the current url in use changes and the sound data have been loaded, indicating that the clip is playing a different sound source. The duration is the length of time in seconds for one cycle of the audio for a pitch set to 1.0. Changing the pitch field will not trigger a duration\_changed event. A duration value of "-1" implies that the sound data have not yet loaded or the value is unavailable for some reason. A duration\_changed event shall be generated if the AudioClip node is loaded when the VRML file is read or the AudioClip node is added to the scene graph. The isActive eventOut may be used by other nodes to determine if the clip is currently active. If an AudioClip is active, it shall be playing the sound corresponding to the sound time (i.e., in the sound's local time system with sample 0 at time 0): ``` t = (now - startTime) modulo (duration / pitch) ``` ## Constructor & Destructor Documentation ### SoVRMLAudioClip::SoVRMLAudioClip (void ) Constructor. ### SoVRMLAudioClip::~SoVRMLAudioClip () \[protected\], \[virtual\] Destructor. ## Member Function Documentation ### SoType SoVRMLAudioClip::getClassTypeId (void ) \[static\] This static method returns the **SoType** object associated with objects of this class. ### SoType SoVRMLAudioClip::getTypeId (void ) const \[virtual\] Returns the type identification of an object derived from a class inheriting **SoBase**. This is used for runtime type checking and "downward" casting. Implements **SoBase**. ### const SoFieldData \*\* SoVRMLAudioClip::getFieldDataPtr (void ) \[static\], \[protected\] *This API member is considered internal to the library, as it is not likely to be of interest to the application programmer.*\ Returns the **SoFieldData** class which holds information about fields in this node. ### const SoFieldData \* SoVRMLAudioClip::getFieldData (void ) const \[protected\], \[virtual\] Returns a pointer to the class-wide field data storage object for this instance. If no fields are present, returns NULL. Reimplemented from **SoFieldContainer**. ### void SoVRMLAudioClip::initClass (void ) \[static\] ### void \* SoVRMLAudioClip::open (const SbStringList & urlref) Opens an audio source with the given *url*. Returns a handle to the datasource. ### size\_t SoVRMLAudioClip::read (void \* datasource, void \* buffer, int numframes, int & channels) Reads *numframes* frames of audio with *channels* channels from *datasource* into *buffer*. Buffer must be allocated by the caller, and must be able to hold all the audio data (size = *numframes* \* *channels* \* sizeof(int16\_t)). The function must always fill the buffer completely unless *buffer* == NULL. When an error occurs, or when end-of-file has been reached, this function returns 0. Otherwise, the function should return *numframes*. When the caller receives a return value of 0, it will queue the returned buffer for playing. When this buffer is finished playing, the caller will call **read()** one final time, with *buffer* == NULL. The **read()** function can then set the isActive field to FALSE, free any resources allocated, etc. ### int SoVRMLAudioClip::seek (void \* datasource, long offset, int whence) Moves the "filepointer" in the *datasource*, returns -1L on error. ### long SoVRMLAudioClip::tell (void \* datasource) Returns the current position of the "filepointer" in the *datasource*, or -1L on error. ### int SoVRMLAudioClip::close (void \* datasource) Closes *datasource*. ### void SoVRMLAudioClip::setCallbacks (open\_func \* opencb, read\_func \* readcb, seek\_func \* seekcb, tell\_func \* tellcb, close\_func \* closecb, void \* userdataptr) Sets callbacks for opening, reading, seeking, telling and closing an audio source. Specifying NULL for a function is OK, except for the read function. If a function set to NULL is later called, a default implementation doing nothing is called in its place. ## Member Data Documentation ### SoSFString SoVRMLAudioClip::description Description of the audio clip. Default value is an empty string. ### SoSFBool SoVRMLAudioClip::loop Specifies whether sound should be looped. Is FALSE by default. ### SoSFFloat SoVRMLAudioClip::pitch Specifies the pitch. The default value is 1.0. Alters the sampling rate at which the sound is played. A pitch of 2.0 means that the sound should be played twice as fast and one octave higher than normal. ### SoSFTime SoVRMLAudioClip::startTime Specifies the start time. Default value is 0. ### SoSFTime SoVRMLAudioClip::stopTime Specifies the stop time. Default value is 0. ### SoMFString SoVRMLAudioClip::url The audio data URL. ### SoSFTime SoVRMLAudioClip::duration\_changed \[protected\] An eventOut sent when a new sound starts playing. ### SoSFBool SoVRMLAudioClip::isActive \[protected\] This eventOut is sent when the sound starts/stops playing. ## Author Generated automatically by Doxygen for Coin from the source code.