hakowork/rojo
3
0
Fork 0
mirror of https://github.com/rojo-rbx/rojo.git synced 2026-10-24 15:01:38 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

update rules

Browse source
This commit is contained in:
Joe 2026-02-02 14:05:11 -06:00
parent 4c390fdd37
commit d5522b2fef
8549 changed files with 11783 additions and 1888 deletions
Download patch file Download diff file Expand all files Collapse all files

106
.cursor/rules/roblox/en-us/audio/assets.md Normal file
View file

@ -0,0 +1,106 @@
---
title: Audio assets
description: Explore how to find and import audio assets for use in your experiences.
---
You can [find](#find-audio) a wide variety of free‑to‑use audio assets in the Creator Store, or you can [import](#import-audio) audio assets that you're certain you have permission to use, such as audio that you make yourself. The [asset privacy](../projects/assets/privacy.md) system automatically ensures that the IDs of your imported audio can't be accessed by users without proper permissions.
## Find audio
The [Creator Store](../production/creator-store.md) tab of the [Toolbox](../projects/assets/toolbox.md) contains a wide variety of free-to-use audio assets made by Roblox and the Roblox community for creators to use within their experiences, including more than 100,000 professionally-produced sound effects and music tracks from top audio and music partners.
To find audio assets on the Creator Store:
1. In the **Toolbox**, navigate to the **Creator Store** tab, then use the category selector dropdown to select **Audio**.
<img src="../assets/studio/toolbox/Creator-Store-Audio.png" width="360" alt="Audio section of Creator Store in Studio's Toolbox" />
2. Use the keyword search, quick filter options, and/or advanced filters to narrow down the results.
<img src="../assets/studio/toolbox/Creator-Store-Audio-Discovery.png" width="580" alt="Audio discovery options in Studio's Toolbox" />
3. Right-click any audio asset, then select **Copy Asset ID** to copy the asset ID to your clipboard. You can now paste this asset ID into a `Class.AudioPlayer` object to [play the audio](../audio/objects.md).
<Alert severity="warning">
If you click any audio asset, Studio inserts it as a new `Class.Sound` instance into the **Explorer** window. However, `Class.Sound` objects don't have the same dynamic functionality as `Class.AudioPlayer` objects.
</Alert>
## Import audio
You can import custom audio through the [Asset Manager](../projects/assets/manager.md), Creator Dashboard, and Open Cloud API as long as your audio meets the following requirements:
- You have the legal rights to that audio asset.
- It adheres to the [Community Rules](https://en.help.roblox.com/hc/articles/203313410) and [Terms of Use](https://en.help.roblox.com/hc/articles/115004647846).
- It's a single track/stream in either `.mp3`, `.ogg`, `.wav` or `.flac` format.
- It's less than 20 MB in size and 7 minutes in duration.
- Its sample rate is less than or equal to 48 kHz.
- Its channels are set to mono or stereo 2.0, 3.0, or 5.1 surround.
If you're [ID verified](../production/publishing/account-verification.md), you can import 100 free audio assets per 30 days; if you're unverified, you can import 10 free audio assets per 30 days. Studio assigns each new audio asset a **unique asset ID** that you can use within your experiences to [play the audio](../audio/objects.md).
<Tabs>
<TabItem key = "1" label="Asset Manager">
To import audio through the **Asset Manager**:
1. Click the **Import** button.
2. Select and then confirm the audio files you want to import from your local system.
3. Once you confirm the imports and the files import successfully, they display with a green checkmark and a completed status.
<Alert severity="info">
To standardize the playback format and check for corrupt or invalid files, Studio transcodes imported audio before saving it as an asset. If you receive an error while importing audio, Studio is likely rejecting it during the transcode process. In addition, some older audio tools generate invalid file headers or frames when exporting.
If Studio continues to reject the audio you're trying to import, ensure your audio tools are updated, then verify that the audio files meet the import requirements.
</Alert>
</TabItem>
<TabItem key = "2" label="Creator Dashboard">
To import audio through the [Creator Dashboard](https://create.roblox.com/dashboard/creations):
1. In the horizontal navigation, select **Development Items**. All assets you have previously imported display within their respective category.
2. In the sub-horizontal navigation, select **Audio**.
3. Click the **Upload Asset** button. The **Upload Asset** page displays.
4. In the **Upload Asset** page,
1. Click the **Upload** button, then select and then confirm the audio file you want to import from your local system.
1. Fill out the **Name** and **Description** fields with the audio file's relevant information.
1. At the bottom of the page, click the **Upload** button.
Your audio assets are now within the moderation queue and are only visible to you within the **Audio** tab of the Creator Dashboard's **Development Items** page.
</TabItem>
<TabItem key = "3" label="Open Cloud API">
To import audio through an HTTP request:
1. Copy the API key to the `x-api-key` request header of the [Create Asset](../reference/cloud/assets/v1.json#POST-v1-assets) endpoint.
1. In your request:
1. Specify that the target asset type is **Audio**.
1. Add your audio asset's name and description.
1. Add the creator information.
- If you want to create the audio asset **on your own behalf**, add your user ID. You can find your user ID on the URL of your Roblox profile. For example, for `https://www.roblox.com/users/1234567/profile`, your user ID is `1234567`.
- If you want to create the audio asset **as a group asset**, add the group ID of your group. You can find the group ID on the URL of your group's page. For example, for `https://www.roblox.com/groups/7654321/example-group#!/`, the group ID is `7654321`.
1. Add the file path and content type of your asset.
```bash title ="Example Request for Create Audio Asset"
curl --location 'https://apis.roblox.com/assets/v1/assets' \
--header 'x-api-key: ${ApiKey}' \
--form 'request="{
\"assetType\": \"Audio\",
\"displayName\": \"Name\",
\"description\": \"This is a description\",
\"creationContext\": {
\"creator\": {
\"userId\": \"${userId}\" # Use groupId for creating a group asset
}
}
}"' \
--form 'fileContent=@"/filepath/audio.mp3";type=audio/mpeg'
```
</TabItem>
</Tabs>
After the audio assets pass moderation, you can reuse them in any project on the platform. Although you are initially the only one who can view and use private audio assets, the [asset privacy](../projects/assets/privacy.md) system lets you grant usage permissions to specific connections and experiences.

225
.cursor/rules/roblox/en-us/audio/effects.md Normal file
View file

@ -0,0 +1,225 @@
---
title: Audio effects
description: Audio effects modify or enhance audio streams in your experiences.
---
Audio effects non-destructively modify or enhance audio streams. You can apply these effects to make your audio more immersive within your experience, such as using an `Class.AudioEqualizer` object to make rain sound muffled, `Class.AudioCompressor` object to control a sound's maximum volume, or `Class.AudioReverb` to add more realistic reflections of sound in interior spaces.
## Apply audio effects
You can apply audio effects to your audio streams by wiring up the effect within your 2D audio or 3D audio setup before it reaches the player's ears. For example, to review the setup instructions in [Audio objects](../audio/objects.md#2d-audio), 2D audio requires an audio player to produce the stream, a physical hardware device like a speaker or headphones, and a wire to carry the audio stream from the audio player to the output device.
<img src="../assets/audio/audio-objects/2D-Audio-Diagram.png" width="100%" />
If you keep this setup the way it is, the audio stream from the asset ID plays as it was originally recorded. However, if you want to apply an audio effect to this audio stream, you must introduce the audio effect in the middle of the configuration so that the audio stream transmits through the effect before it transmits to the output device.
<img src="../assets/audio/effects/AudioEffect-Single.png" width="100%" />
Roblox's modular audio objects also allow you to wire multiple audio players through an audio effect, meaning that you don't have to have multiple audio effect objects with the same settings. This provides a lot of flexibility in how you customize multiple audio sources at once.
<img src="../assets/audio/effects/AudioEffect-Multiple.png" width="100%" />
In addition, you can apply multiple audio effects to the same audio stream to further customize your audio. As the audio stream transmits from the audio player to the device output, it's important to note that the order of the audio effects impacts the custom sound. For example, if you were to apply an `Class.AudioChorus` effect first, then an `Class.AudioDistortion` effect second, your custom sound may sound different from a configuration that applies the `Class.AudioDistortion` effect before the `Class.AudioChorus` effect.
<img src="../assets/audio/effects/AudioEffect-Layered.png" width="100%" />
Each audio effect you apply has additional properties you can adjust until you achieve the type of sound you desire. For more information on these properties, see each audio effect's API page.
## Types
### Equalizer
`Class.AudioEqualizer` allows for control of the volume of various frequency ranges. This audio effect is useful to highlight or minimize particular elements of audio, such as muffling all audio in your experience when a player goes underwater.
<GridContainer numColumns="2">
<figure>
<figcaption>Without `Class.AudioEqualizer` effect</figcaption>
<br />
<audio controls>
<source src="../assets/audio/dynamic-effects/no-effect.mp3" type="audio/mpeg"></source>
</audio>
</figure>
<figure>
<figcaption>With `Class.AudioEqualizer` effect</figcaption>
<br />
<audio controls>
<source src="../assets/audio/dynamic-effects/equalizer.mp3" type="audio/mpeg"></source>
</audio>
</figure>
</GridContainer>
### Compressor
`Class.AudioCompressor` reduces the dynamic range of audio by lowering the volume of the highest parts of a source while at the same time raising the overall volume. This audio effect is useful to set a consistent volume for players to hear even if you record audio while whispering or speaking loudly. You can also use this dynamic effect to prioritize audio streams over another through the process of ducking.
<GridContainer numColumns="2">
<figure>
<figcaption>Without `Class.AudioCompressor` effect</figcaption>
<br />
<audio controls>
<source src="../assets/audio/dynamic-effects/no-effect.mp3" type="audio/mpeg"></source>
</audio>
</figure>
<figure>
<figcaption>With `Class.AudioCompressor` effect</figcaption>
<br />
<audio controls>
<source src="../assets/audio/dynamic-effects/compressor.mp3" type="audio/mpeg"></source>
</audio>
</figure>
</GridContainer>
### Reverb
`Class.AudioReverb` simulates the effect of sounds bouncing off of several surfaces. This audio effect is useful to simulate more realistic reflections of sounds in interior spaces, such as bouncing a basketball inside a gymnasium, or playing rock music in a stadium.
<GridContainer numColumns="2">
<figure>
<figcaption>Without `Class.AudioReverb` effect</figcaption>
<br />
<audio controls>
<source src="../assets/audio/dynamic-effects/no-effect.mp3" type="audio/mpeg"></source>
</audio>
</figure>
<figure>
<figcaption>With `Class.AudioReverb` effect</figcaption>
<br />
<audio controls>
<source src="../assets/audio/dynamic-effects/reverb.mp3" type="audio/mpeg"></source>
</audio>
</figure>
</GridContainer>
### Chorus
`Class.AudioChorus` simulates the effect of multiple vocals or instruments playing simultaneously by taking the original sound and overlaying copies, each with slight variations in pitch. This audio effect is useful for simulating a robotic or futuristic quality to your audio.
<GridContainer numColumns="2">
<figure>
<figcaption>Without `Class.AudioChorus` effect</figcaption>
<br />
<audio controls>
<source src="../assets/audio/dynamic-effects/no-effect.mp3" type="audio/mpeg"></source>
</audio>
</figure>
<figure>
<figcaption>With `Class.AudioChorus` effect</figcaption>
<br />
<audio controls>
<source src="../assets/audio/dynamic-effects/chorus.mp3" type="audio/mpeg"></source>
</audio>
</figure>
</GridContainer>
### Distortion
`Class.AudioDistortion` simulates the effect that would occur when overdriving older style audio equipment. This audio effect causes clipping in the sound and adds a general "fuzziness," which is useful for either adding intensity and character to musical instruments.
<GridContainer numColumns="2">
<figure>
<figcaption>Without `Class.AudioDistortion` effect</figcaption>
<br />
<audio controls>
<source src="../assets/audio/dynamic-effects/no-effect.mp3" type="audio/mpeg"></source>
</audio>
</figure>
<figure>
<figcaption>With `Class.AudioDistortion` effect</figcaption>
<br />
<audio controls>
<source src="../assets/audio/dynamic-effects/distortion.mp3" type="audio/mpeg"></source>
</audio>
</figure>
</GridContainer>
### Echo
`Class.AudioEcho` causes a sound to repeat on a delay with diminishing volume, simulating the real effect of an echo that bounces off of hard surfaces, such as walls and caves.
<GridContainer numColumns="2">
<figure>
<figcaption>Without `Class.AudioEcho` effect</figcaption>
<br />
<audio controls>
<source src="../assets/audio/dynamic-effects/no-effect.mp3" type="audio/mpeg"></source>
</audio>
</figure>
<figure>
<figcaption>With `Class.AudioEcho` effect</figcaption>
<br />
<audio controls>
<source src="../assets/audio/dynamic-effects/echo.mp3" type="audio/mpeg"></source>
</audio>
</figure>
</GridContainer>
### Flanger
`Class.AudioFlanger` creates a sweeping or whooshing effect by copying the original audio signal and playing it slightly offset and modulated on top of the original. This audio effect is useful for adding strange, otherworldly digital quality to your audio. For example, you can use it on an air conditioner recording to make a sci‑fi spaceship engine rumble.
<GridContainer numColumns="2">
<figure>
<figcaption>Without `Class.AudioFlanger` effect</figcaption>
<br />
<audio controls>
<source src="../assets/audio/dynamic-effects/no-effect.mp3" type="audio/mpeg"></source>
</audio>
</figure>
<figure>
<figcaption>With `Class.AudioFlanger` effect</figcaption>
<br />
<audio controls>
<source src="../assets/audio/dynamic-effects/flange.mp3" type="audio/mpeg"></source>
</audio>
</figure>
</GridContainer>
### Pitch Shift
`Class.AudioPitchShifter` raises or lowers pitch without changing the playback speed. This audio effect is useful for changing the scale of your sounds. You can use it to make small sounds feel huge by pitching them down or conversely pitch sounds up to make an explosion sound more like a balloon pop.
<GridContainer numColumns="2">
<figure>
<figcaption>Without `Class.AudioPitchShifter` effect</figcaption>
<br />
<audio controls>
<source src="../assets/audio/dynamic-effects/no-effect.mp3" type="audio/mpeg"></source>
</audio>
</figure>
<figure>
<figcaption>With `Class.AudioPitchShifter` effect</figcaption>
<br />
<audio controls>
<source src="../assets/audio/dynamic-effects/pitch-shift.mp3" type="audio/mpeg"></source>
</audio>
</figure>
</GridContainer>
### Tremolo
`Class.AudioTremolo` creates a trembling effect on a sound by varying its volume up and down. This dynamic effect is useful to transform instrument sounds into a wavy, dreamlike quality, or to create swells and dips in weather‑related audio.
<GridContainer numColumns="2">
<figure>
<figcaption>Without `Class.AudioTremolo` effect</figcaption>
<br />
<audio controls>
<source src="../assets/audio/dynamic-effects/no-effect.mp3" type="audio/mpeg"></source>
</audio>
</figure>
<figure>
<figcaption>With `Class.AudioTremolo` effect</figcaption>
<br />
<audio controls>
<source src="../assets/audio/dynamic-effects/tremolo.mp3" type="audio/mpeg"></source>
</audio>
</figure>
</GridContainer>
### Fader
The `Class.AudioFader` adjusts the volume of audio streams to be either higher or lower. This audio effect is useful to control the volume and audio effects properties of multiple audio streams at once.
### Analyzer
The `Class.AudioAnalyzer` analyzes volume and frequency contents. This audio effect is useful for getting information to understanding how your audio is working together, both in volume and frequency content.

29
.cursor/rules/roblox/en-us/audio/index.md Normal file
View file

@ -0,0 +1,29 @@
---
title: Audio
description: An overview of audio features on Roblox.
---
Adding audio to your experiences is crucial for elevating your experiences to new heights. By strategically using positional and non-positional audio, you can immerse players into your worlds, provide them useful feedback for their actions, and direct their attention to what they need to do to be successful in their objectives.
## Audio assets
You can import [audio assets](../audio/assets.md) that you're certain you have permission to use, such as audio that you make yourself. However, Roblox's [Creator Store](../production/creator-store.md) provides you a wide variety of free-to-use audio assets, including more than 100,000 professionally-produced sound effects and music tracks from top audio and music partners.
## Audio objects
Roblox offers many different types of [audio objects](../audio/objects.md) that you can use to play and modify your audio until it meets your experience's design requirements:
- The `Class.AudioPlayer` object loads and plays the **audio file** using a set [audio asset ID](../audio/assets.md).
- The `Class.AudioEmitter` object is a **virtual speaker** that emits audio into the 3D environment.
- The `Class.AudioListener` object is a **virtual microphone** that picks up audio from the 3D environment.
- The `Class.AudioDeviceOutput` object is a **physical hardware device** within the real world, such as a speaker or headphones.
- The `Class.AudioDeviceInput` object is a **physical microphone** within the real world.
- The `Class.AudioTextToSpeech` object converts **text to audio** using an artificial voice.
- The `Class.AudioSpeechToText` object converts **audio to text**.
- `Class.Wire|Wires` carry audio streams from one object to another.
Using these objects, you can either set audio to play automatically at runtime, or trigger it to play from scripts. For practical applications of these audio objects, see the [Add 2D audio](../tutorials/use-case-tutorials/audio/add-2D-audio.md), [Add 3D audio](../tutorials/use-case-tutorials/audio/add-3D-audio.md), [Add text-to-speech](../tutorials/use-case-tutorials/audio/add-text-to-speech.md), [Add speech-to-text](../tutorials/use-case-tutorials/audio/speech-to-text.md), and [Add voice chat](../tutorials/use-case-tutorials/audio/add-voice-chat.md) tutorials.
## Audio effects
[Audio effects](../audio/effects.md) non-destructively modify or enhance audio streams from `Class.AudioPlayer` objects. You can apply these effects to make your environments more captivating and immersive, such as using a `Class.AudioEqualizer` object to make rain sound muffled, `Class.AudioCompressor` object to control a sound's maximum volume, or `Class.AudioReverb` to add more realistic reflections of sound in interior spaces.

445
.cursor/rules/roblox/en-us/audio/objects.md Normal file
View file

@ -0,0 +1,445 @@
---
title: Audio objects
description: An overview of modular audio objects on Roblox.
---
Roblox's modular audio objects allow you to have dynamic control over sound and voice chat in your experiences. Almost every audio object corresponds to a real-world audio device, and they all function together to capture and play audio like their physical counterparts.
For example, every audio object conceptually falls into the following categories:
- Objects that **produce** audio streams, such as audio players.
- Objects that **consume** audio streams, such as audio emitters.
- Objects that **modify** audio streams, such as audio effects.
- Objects that **carry** audio streams from one audio object to another, such as wires.
As you read through this guide and learn about how all of these audio objects work together to emit sound, you will learn how to accurately capture and feed music, sound effects, and the human voice from the experience to the player and vice-versa.
<Alert severity = 'info'>
`Class.Sound`, `Class.SoundGroup`, and `Class.SoundEffect` objects are now discouraged in favor of the more robust functionality of audio objects.
</Alert>
## Play audio
To play audio within your experience, it's important to understand the role of each available audio object:
- An `Class.AudioPlayer` loads and plays the **audio file** using a set audio asset ID.
- An `Class.AudioEmitter` is a **virtual speaker** that emits audio into the 3D environment.
- An `Class.AudioListener` is a **virtual microphone** that picks up audio from the 3D environment.
- An `Class.AudioDeviceOutput` is a **physical hardware device** within the real world, such as a speaker or headphones.
- An `Class.AudioDeviceInput` is a **physical microphone** within the real world.
- The `Class.AudioTextToSpeech` object converts **text to audio** using an artificial human voice.
- The `Class.AudioSpeechToText` object converts **spoken audio to text**.
- A `Class.Wire` **carries audio streams** from one audio object to another.
How you pair these audio objects together depends on if you want to emit audio directly to the player's speaker or headphones or from objects in the 3D space. The following sections detail both scenarios.
### 2D audio
**2D audio** is non-directional sound that plays from no particular location, remaining at the same volume regardless of the player's position or orientation in the 3D space. This type of audio requires three audio objects:
- An audio player to produce an audio stream.
- A physical hardware device to play the audio stream in the real world.
- A wire to carry the audio stream from the audio player to the output device.
To demonstrate how to configure these audio objects in Studio for 2D audio, the following diagram compares each object with their real world audio device counterpart. In summary:
- The `Class.AudioPlayer` loads and plays your audio asset with specified settings.
- The `Class.AudioDeviceOutput` allows the player to hear the audio through their speaker or headphones.
- The `Class.Wire` connects to the audio player with its `Class.Wire.SourceInstance|SourceInstance` property, and to the physical hardware device with its `Class.Wire.TargetInstance|TargetInstance` property. It then acts as a bridge to carry the audio stream from the audio player to the player's output device.
<img src="../assets/audio/audio-objects/2D-Audio-Diagram.png" width="100%" />
To play non-directional audio:
1. In the **Explorer** window, go to **SoundService** and insert the following:
1. An **AudioPlayer** object to create an audio source.
1. An **AudioDeviceOutput** object to create a speaker that plays throughout the experience.
1. A **Wire** object to connect the stream from the audio player to the speaker.
1. In the **Properties** window of the **AudioPlayer** object:
1. Set **AssetID** to a valid audio asset ID. If you don't have your own custom audio, you can find free-to-use audio assets in the Creator Store.
1. Enable **Looping** if you want your audio to continuously repeat.
1. Set **Volume** to the unit of amplitude you want to play your audio.
1. In the **Properties** window of the **Wire** object:
1. Set **SourceInstance** to the **AudioPlayer** to specify that you want to play the audio within this specific audio player.
1. Set **TargetInstance** to the **AudioDeviceOutput** to specify that you want to play the audio from this specific speaker.
From here, you can trigger your non-directional audio with scripts to either play as players join the experience or as a result of a gameplay event or UI interaction. For code sample references for these use cases, see the [Add 2D audio](../tutorials/use-case-tutorials/audio/add-2D-audio.md) tutorial.
### 3D audio
**3D audio** is directional sound that plays from a particular location in the 3D space, increasing or decreasing in volume depending on the player's position and orientation to the sound. This type of audio requires six audio objects:
- An audio player to produce an audio stream.
- An audio emitter to emit the audio stream within the environment.
- A listener to pick up the audio stream from the environment.
- A physical hardware device to play the audio stream in the real world.
- Two wires: one to carry the audio stream from the audio player to the emitter, and another to carry it from the listener to the output device.
To demonstrate how to configure these audio objects in Studio for 3D audio, the following diagram compares each object with their real world audio device counterpart. In summary:
- The `Class.AudioPlayer` loads and plays your audio asset with specified settings.
- The `Class.AudioEmitter`'s parent position in the 3D space determines where that audio emits within the environment.
- The `Class.AudioListener` either picks up audio from the emitter from the local camera or within the player character's `Class.Humanoid.RootPart`, depending on where you set the default listener position.
- The `Class.AudioDeviceOutput` allows the player to hear the audio through their speaker or headphones.
- The first `Class.Wire` connects to the audio player with its `Class.Wire.SourceInstance|SourceInstance` property, and to the emitter with its `Class.Wire.TargetInstance|TargetInstance` property. It then acts as a bridge to carry the audio stream from the audio player to the emitter.
- The second `Class.Wire` connects to the listener with its `Class.Wire.SourceInstance|SourceInstance` property, and to the physical hardware device with its `Class.Wire.TargetInstance|TargetInstance` property. It then acts as a bridge to carry the audio stream from the listener to the player's output device.
<img src="../assets/audio/audio-objects/3D-Audio-Diagram.png" width="100%" />
To play positional audio:
1. Choose where you want to create an **AudioListener** when players spawn into the experience.
1. In the **Explorer** window, select **SoundService**.
1. In the **Properties** window, set **ListenerLocation** to one of the following:
- **Default** - Creates and parents the listener to `Class.Workspace.CurrentCamera` in experiences that enable voice chat.
- **None** - Does not create a listener. This option is useful if you want to create a listener through a script.
- **Character** - Creates and parents a listener to the local player's character.
- **Camera** - Creates and parents the listener to `Class.Workspace.CurrentCamera`.
<Alert severity = 'info'>
When you set **ListenerLocation** to either **Character** or **Camera**, the engine automatically creates an `Class.AudioDeviceOutput` object under `Class.SoundService` at runtime.
</Alert>
1. In the **Explorer** window, go to the 3D object that you want to emit audio and insert the following:
1. An **AudioPlayer** object to create an audio source.
1. An **AudioEmitter** object to emit a positional stream from the 3D object.
1. A **Wire** object to connect the stream from the audio player to the audio emitter.
1. In the **Properties** window of the **AudioPlayer** object:
1. Set **AssetID** to a valid audio asset ID. If you don't have your own custom audio, you can find free-to-use audio assets in the Creator Store.
1. Enable **Looping** if you want your audio to continuously repeat.
1. Set **Volume** to the unit of amplitude you want to play your audio.
1. In the **Properties** window of the **AudioEmitter** object, set **DistanceAttenuation** to a volume-over-distance curve that determines how loudly the listener hears the emitter according to the distance between them.
For example, the following curve decreases the audio's volume in half when the listener is 50 studs away from the emitter, then it sharply decreases the volume to zero when the listener is 70 studs away.
<img src="../assets/audio/audio-objects/DistanceAttenuation.png" width="60%" />
1. In the **Properties** window of the **Wire** object:
1. Set **SourceInstance** to the **AudioPlayer** to specify that you want to play the audio within this specific audio player.
1. Set **TargetInstance** to the **AudioEmitter** to specify that you want to play the audio from this specific audio emitter.
From here, you can trigger your directional audio with scripts to either play as players join the experience or as a result of a gameplay event or UI interaction. For code sample references for these use cases, see the [Add 3D audio](../tutorials/use-case-tutorials/audio/add-3D-audio.md) tutorial.
### Text-to-speech
<Alert severity="warning">
All text for `Class.AudioTextToSpeech` objects must adhere to Roblox's [Community Standards](https://en.help.roblox.com/hc/en-us/articles/203313410-Roblox-Community-Standards) and [Terms of Use](https://en.help.roblox.com/hc/articles/115004647846).
</Alert>
**Text-to-speech** (**TTS**) is a form of assistive technology that converts text strings into speech sounds using an artificial voice. This type of audio requires five audio objects:
- An audio speech generator to load and convert text into audio.
- An audio emitter to emit the audio stream within the environment.
- A listener to pick up the audio stream from the environment.
- A physical hardware device to play the audio stream in the real world.
- For 2D audio - A wire to carry the audio stream from the audio speech generator to the output device.
- For 3D audio - Two wires: one to carry the audio stream from the audio speech generator to the emitter, and another to carry it from the listener to the output device.
How you configure these objects depends on if you want to create 2D TTS audio or 3D TTS audio. For more details on either process, click between the following tabs.
<Tabs>
<TabItem key = "1" label="2D Text-to-Speech">
To demonstrate how to configure these audio objects in Studio for 2D TTS audio, the following diagram compares each object with their real world audio device counterpart. In summary:
- The `Class.AudioTextToSpeech` object loads and converts text strings into speech sounds.
- The `Class.AudioDeviceOutput` allows the player to hear the audio through their speaker or headphones.
- The `Class.Wire` connects to the audio speech generator with its `Class.Wire.SourceInstance|SourceInstance` property, and to the physical hardware device with its `Class.Wire.TargetInstance|TargetInstance` property. It then acts as a bridge to carry the audio stream from the audio speech generator to the player's output device.
<img src="../assets/audio/audio-objects/TTS2D-Audio-Diagram.png" width="100%" />
To play 2D text-to-speech audio:
1. In the **Explorer** window, go to **SoundService** and insert the following:
1. An **AudioTextToSpeech** object to create an audio speech generator.
1. An **AudioDeviceOutput** object to create a speaker that plays throughout the experience.
1. A **Wire** object to connect the stream from the audio speech generator to the speaker.
1. In the **Properties** window of the **AudioTextToSpeech** object:
1. Set **Text** to anything you want the voice to say. There is a limit of 300 characters per request.
1. Set **VoiceId** to a number between `1` and `10`, depending on which artificial voice you want to use in the following table.
<BaseAccordion>
<AccordionSummary>
<Typography variant="label1">List of artificial voices</Typography>
</AccordionSummary>
<AccordionDetails>
<table>
<thead>
<tr>
<th>VoiceID</th>
<th>Voice Description</th>
<th>Audio Example</th>
</tr>
</thead>
<tbody>
<tr>
<td>1</td>
<td>British male</td>
<td><audio controls><source src="../assets/audio/audio-objects/British-Male-Voice.wav" type="audio/mpeg"></source></audio></td>
</tr>
<tr>
<td>2</td>
<td>British female</td>
<td><audio controls><source src="../assets/audio/audio-objects/British-Female-Voice.wav" type="audio/mpeg"></source></audio></td>
</tr>
<tr>
<td>3</td>
<td>United States male #1</td>
<td><audio controls><source src="../assets/audio/audio-objects/US-Male-Voice-1.wav" type="audio/mpeg"></source></audio></td>
</tr>
<tr>
<td>4</td>
<td>United States female #1</td>
<td><audio controls><source src="../assets/audio/audio-objects/US-Female-Voice-1.wav" type="audio/mpeg"></source></audio></td>
</tr>
<tr>
<td>5</td>
<td>United States male #2</td>
<td><audio controls><source src="../assets/audio/audio-objects/US-Male-Voice-2.wav" type="audio/mpeg"></source></audio></td>
</tr>
<tr>
<td>6</td>
<td>United States female #2</td>
<td><audio controls><source src="../assets/audio/audio-objects/US-Female-Voice-2.wav" type="audio/mpeg"></source></audio></td>
</tr>
<tr>
<td>7</td>
<td>Australian male</td>
<td><audio controls><source src="../assets/audio/audio-objects/Australian-Male-Voice.wav" type="audio/mpeg"></source></audio></td>
</tr>
<tr>
<td>8</td>
<td>Australian female</td>
<td><audio controls><source src="../assets/audio/audio-objects/Australian-Female-Voice.wav" type="audio/mpeg"></source></audio></td>
</tr>
<tr>
<td>9</td>
<td>Retro voice #1</td>
<td><audio controls><source src="../assets/audio/audio-objects/Retro-Voice-1.wav" type="audio/mpeg"></source></audio></td>
</tr>
<tr>
<td>10</td>
<td>Retro voice #2</td>
<td><audio controls><source src="../assets/audio/audio-objects/Retro-Voice-2.wav" type="audio/mpeg"></source></audio></td>
</tr>
</tbody>
</table>
</AccordionDetails>
</BaseAccordion>
<br></br>
1. Set **Volume** to the unit of amplitude you want to play your audio.
1. In the **Properties** window of the **Wire** object:
1. Set **SourceInstance** to the **AudioTextToSpeech** to specify that you want to play the audio within this specific audio speech generator.
1. Set **TargetInstance** to the **AudioDeviceOutput** to specify that you want to play the audio from this specific speaker.
</TabItem>
<TabItem key = "2" label="3D Text-to-Speech">
To demonstrate how to configure these audio objects in Studio for 3D TTS audio, the following diagram compares each object with their real world audio device counterpart. In summary:
- The `Class.AudioTextToSpeech` object loads and converts text strings into speech sounds.
- The `Class.AudioEmitter`'s parent position in the 3D space determines where that audio emits within the environment.
- The `Class.AudioListener` either picks up audio from the emitter from the local camera or within the player character's `Class.Humanoid.RootPart`, depending on where you set the default listener position.
- The `Class.AudioDeviceOutput` allows the player to hear the audio through their speaker or headphones.
- The first `Class.Wire` connects to the audio speech generator with its `Class.Wire.SourceInstance|SourceInstance` property, and to the emitter with its `Class.Wire.TargetInstance|TargetInstance` property. It then acts as a bridge to carry the audio stream from the audio speech generator to the emitter.
- The second `Class.Wire` connects to the listener with its `Class.Wire.SourceInstance|SourceInstance` property, and to the physical hardware device with its `Class.Wire.TargetInstance|TargetInstance` property. It then acts as a bridge to carry the audio stream from the listener to the player's output device.
<img src="../assets/audio/audio-objects/TTS3D-Audio-Diagram.png" width="100%" />
To play 3D text-to-speech audio:
1. Choose where you want to create an **AudioListener** when players spawn into the experience.
1. In the **Explorer** window, select **SoundService**.
1. In the **Properties** window, set **ListenerLocation** to one of the following:
- **Default** - Creates and parents the listener to `Class.Workspace.CurrentCamera` in experiences that enable voice chat.
- **None** - Does not create a listener. This option is useful if you want to create a listener through a script.
- **Character** - Creates and parents a listener to the local player's character.
- **Camera** - Creates and parents the listener to `Class.Workspace.CurrentCamera`.
<Alert severity = 'info'>
When you set **ListenerLocation** to either **Character** or **Camera**, the engine automatically creates an `Class.AudioDeviceOutput` object under `Class.SoundService` at runtime.
</Alert>
1. In the **Explorer** window, go to the 3D object that you want to emit audio and insert the following:
1. Aan **AudioTextToSpeech** object to create an audio speech generator.
1. An **AudioEmitter** object to emit a positional stream from the 3D object.
1. A **Wire** object to connect the stream from the audio speech generator to the audio emitter.
1. In the **Properties** window of the **AudioTextToSpeech** object:
1. Set **Text** to anything you want the voice to say. There is a limit of 300 characters per request.
1. Set **VoiceId** to a number between `1` and `10`, depending on which artificial voice you want to use in the following table.
<BaseAccordion>
<AccordionSummary>
<Typography variant="label1">List of artificial voices</Typography>
</AccordionSummary>
<AccordionDetails>
<table>
<thead>
<tr>
<th>VoiceID</th>
<th>Voice Description</th>
<th>Audio Example</th>
</tr>
</thead>
<tbody>
<tr>
<td>1</td>
<td>British male</td>
<td><audio controls><source src="../assets/audio/audio-objects/British-Male-Voice.wav" type="audio/mpeg"></source></audio></td>
</tr>
<tr>
<td>2</td>
<td>British female</td>
<td><audio controls><source src="../assets/audio/audio-objects/British-Female-Voice.wav" type="audio/mpeg"></source></audio></td>
</tr>
<tr>
<td>3</td>
<td>United States male #1</td>
<td><audio controls><source src="../assets/audio/audio-objects/US-Male-Voice-1.wav" type="audio/mpeg"></source></audio></td>
</tr>
<tr>
<td>4</td>
<td>United States female #1</td>
<td><audio controls><source src="../assets/audio/audio-objects/US-Female-Voice-1.wav" type="audio/mpeg"></source></audio></td>
</tr>
<tr>
<td>5</td>
<td>United States male #2</td>
<td><audio controls><source src="../assets/audio/audio-objects/US-Male-Voice-2.wav" type="audio/mpeg"></source></audio></td>
</tr>
<tr>
<td>6</td>
<td>United States female #2</td>
<td><audio controls><source src="../assets/audio/audio-objects/US-Female-Voice-2.wav" type="audio/mpeg"></source></audio></td>
</tr>
<tr>
<td>7</td>
<td>Australian male</td>
<td><audio controls><source src="../assets/audio/audio-objects/Australian-Male-Voice.wav" type="audio/mpeg"></source></audio></td>
</tr>
<tr>
<td>8</td>
<td>Australian female</td>
<td><audio controls><source src="../assets/audio/audio-objects/Australian-Female-Voice.wav" type="audio/mpeg"></source></audio></td>
</tr>
<tr>
<td>9</td>
<td>Retro voice #1</td>
<td><audio controls><source src="../assets/audio/audio-objects/Retro-Voice-1.wav" type="audio/mpeg"></source></audio></td>
</tr>
<tr>
<td>10</td>
<td>Retro voice #2</td>
<td><audio controls><source src="../assets/audio/audio-objects/Retro-Voice-2.wav" type="audio/mpeg"></source></audio></td>
</tr>
</tbody>
</table>
</AccordionDetails>
</BaseAccordion>
<br></br>
1. Set **Volume** to the unit of amplitude you want to play your audio.
1. In the **Properties** window of the of the **AudioEmitter**, set **DistanceAttenuation** to a volume-over-distance curve that determines how loudly the listener hears the emitter according to the distance between them.
For example, the following curve decreases the audio's volume in half when the listener is 50 studs away from the emitter, then it sharply decreases the volume to zero when the listener is 70 studs away.
<img src="../assets/audio/audio-objects/DistanceAttenuation.png" width="60%" />
1. In the **Properties** window of the **Wire** object:
1. Set **SourceInstance** to the **AudioTextToSpeech** to specify that you want to play the audio within this specific audio speech generator.
1. Set **TargetInstance** to the **AudioEmitter** to specify that you want to play the audio from this specific audio emitter.
</TabItem>
</Tabs>
From here, you can trigger your TTS audio with scripts. For code sample references for TTS audio, including how to configure context-aware TTS that adapts in relation to the player, the state of their environment, or gameplay status, see the [Add text-to-speech](../tutorials/use-case-tutorials/audio/add-text-to-speech.md) tutorial.
### Speech-to-text
<Alert severity="warning">
All audio for `Class.AudioSpeechToText` objects must adhere to Roblox's [Community Standards](https://en.help.roblox.com/hc/en-us/articles/203313410-Roblox-Community-Standards) and [Terms of Use](https://en.help.roblox.com/hc/articles/115004647846).
</Alert>
**Speech-to-text** (**STT**) is a form of technology that automatically generates text strings from speech sounds. This type of audio requires three audio objects:
- A text generator to load and convert audio into text.
- A physical hardware device like a microphone to capture the audio input.
- A wire to carry the audio stream from the input device to the text generator.
All of these audio objects work together to generate STT text in response to player actions. For example, if the player is wearing a headset while playing an experience with their laptop:
- The `Class.AudioDeviceInput` captures the player's speech, as spoken into their microphone and as a stream of audio.
- A `Class.Wire` carries the audio stream from the `Class.AudioDeviceInput` to the `Class.AudioSpeechToText`.
- The `Class.AudioSpeechToText` converts the player's speech into text.
- The experience reads this text and performs an action, such as displaying the spoken text on the screen or opening a door at the player's command.
<img src="../assets/audio/audio-objects/STT-Audio-Diagram.png" width="100%" />
To implement speech-to-text in your experience:
1. Enable the use of the latest API for voice.
1. In the **Explorer** window, select the **VoiceChatService**.
2. In the **Properties** window, set **UseAudioApi** to **Enabled**.
2. In the **Explorer** window, go to **SoundService** and insert the following:
1. An **AudioDeviceInput** to capture speech.
2. An **AudioSpeechToText** to convert the speech into text.
3. A **Wire** to carry the stream from the audio device input to the STT instance.
3. In the **Properties** window of the **AudioSpeechToText** object, set the **Enabled** state to on.
4. In the **Properties** window of the **Wire** object:
1. Set **SourceInstance** to your new **AudioDeviceInput** to specify that you want the wire to carry audio from this specific audio instance.
2. Set **TargetInstance** to your new **AudioSpeechToText** to specify that you want the wire to carry audio to this specific audio instance.
5. Set the **Player** property of the audio device input to the local player at runtime with `audioDeviceInput.Player = game.Players.LocalPlayer`. This tells Roblox which user's microphone to capture audio from.
<Alert severity="info">
By default, enabling the microphone also enables spatial voice chat in your experience. If you want players to use speech-to-text without broadcasting their voice to other players, turn off the **EnableDefaultVoice** property under **VoiceChatService**.
</Alert>
After setting up STT in your experience, you can trigger it with scripts. For code sample references, see the [Add speech-to-text](../tutorials/use-case-tutorials/audio/speech-to-text.md) tutorial.
<h5 style={{marginTop: '36px'}}>Filter for similar words</h5>
When you implement STT in your experience, you might want to improve matching accuracy by filtering for words that sound similar to the words you actually want the player to say. To do this, you can compare the words recognized by `AudioSpeechToText` with known word lists:
1. Sanitize and tokenize the `Text` output of `AudioSpeechToText` to create a table of lowercase strings that can be parsed and compared.
1. Remove punctuation characters.
2. Convert the entire string to lowercase.
3. Split the string by whitespace to produce a table of words.
2. Generate candidate tables to prepare your strings for comparison.
1. Sanitize and tokenize each reference string.
2. Store these processed words in a separate table.
3. Compare and match the words in both tables to recognize the speech inputs that are close to your target phrases, even if they include small variations.
- For simple checks, check if the strings are the exact same.
- For more flexible matching, you can write custom logic to accept substitutions (like "colour" instead of "color") or match a subset of words and calculate a similarity score.
## Customize audio
Audio effects allow you to non-destructively modify or enhance audio streams before they reach a player's ears. You can apply these effects to make your audio more immersive within experiences, such as using an `Class.AudioEqualizer` object to make rain sound muffled, `Class.AudioCompressor` object to control a sound's maximum volume, or `Class.AudioReverb` to add more realistic reflections of sound in interior spaces.
For instructions on how to configure audio effects, as well as side-by-side comparisons of before and after you customize your audio, see [Audio effects](../audio/effects.md).
<img src="../assets/audio/effects/AudioEffect-Single.png" width="80%" />
<img src="../assets/audio/effects/AudioEffect-Multiple.png" width="80%" />
## Trigger audio
You can trigger audio contextually from a script by calling `Class.AudioPlayer.Play|Play()` on an `Class.AudioPlayer` object that's correctly wired up. For example, if you parent a script to an audio player, you can trigger the audio asset through something like this:
``` lua
local audio = script.Parent
local something = ...
something.SomeEvent:Connect(function()
audio:Play()
end)
```
For more complex code samples to trigger audio, such as for gameplay feedback, UI interactions, and looping background noise, see the [Add 2D audio](../tutorials/use-case-tutorials/audio/add-2D-audio.md), [Add 3D audio](../tutorials/use-case-tutorials/audio/add-3D-audio.md), and [Add text-to-speech](../tutorials/use-case-tutorials/audio/add-text-to-speech.md) tutorials.