Audio

Audio is a powerful tool for enhancing immersion and engagement in your experiences.

Supported formats

Mattercraft currently supports the following audio formats:

  • MP3
  • M4A
  • OGG

Adding Audio

Integrating audio into your project is straightforward with Mattercraft. You have two simple options:

Drag and Drop

Simply drag and drop your audio into the project files menu:

Dragging Audio into the Left Menu

From your Computer

Click on the + (plus) icon in the project files menu (located in the Left Menu) and select From your computer to browse and import your audio.

Adding Audio 'From your computer'

Once you've added your audio clip to the Hierarchy, you can choose whether it is a normal audio clip or a positional audio clip.

Clip type Description
Normal Audio Normal audio will play at the set volume and will not require a position in 3D space.
Positional Audio Positional audio can be placed in 3D space and will change based on the user's position relative to the audio's position in the scene. You can update properties like Ref Distance, Rolloff Factor, and Max Distance for positional audio to ensure it plays as expected when positioned.

Playing Audio

Once you have added your audio to the Hierarchy, you have several options for playing it:

Autoplay

Enable the Autoplay option in the properties to automatically start the audio when your zcomp is loaded:

Autoplay audio property

Stream Action

Use a stream track action to trigger audio playback via an event:

Stream actions behavior

Select the node in the Hierarchy that you want the event to fire on, choose Stream Actions, and use the desired action (e.g., Play Stream).

To learn more about adding interactivity to your Mattercraft projects, see our dedicated Behavior Actions articles.

Stream Tracks

You can add audio to a timeline by using its stream track:

Add Audio clips as Stream Tracks

To utilize this feature, follow these steps:

  1. Click on the Animations panel to open it up
  2. Click on Layers if your Timeline is inside a layer or Clips if it is independent
  3. Find and click on the Timeline you wish to add the Stream Track to
  4. Go to the Timeline Clip editor and find the + (plus) icon
  5. Find Streams and then click on the audio you wish to add to the Timeline
  6. Mattercraft will automatically add the Stream Track to the Timeline

You can then use standard timeline methods to edit and update the audio along the timeline, such as changing the start, end, offset start, and playback rate (by double clicking on the audio bar).

To learn more about timelines and playing stream tracks in Mattercraft, check out our dedicated Stream Tracks article.

In a Script

To play audio clips in a script, use:

this.instance.play()

If you're using this in a behavior that isn't directly instancing the audio, replace this.instance. with this.nodes.zcomponent.YourAudioNode.

You can also listen for events that the audio fires using:

// When the video this code references is playing...
this.register(this.instance.onPlay, evt => {

    // Code to handle event
    console.log("Audio is playing!");

});

Replace onPlay with the event you want to listen for.

zapcode branded_zapcode i