Audio¶
Contents
The object AUDIO allows you to add and play audio to your project resources, control playback, change the volume and select an audio file.
Working with object AUDIO¶
Object AUDIO properties¶
| Parameter | Description | Note |
|---|---|---|
| Ресурс аудио (audioResource) | Allows to select an audio file of the required format. | Upon creating an object AUDIO, the audio resource is not defined. In order to add an audio resource, one needs to select one of the pre-uploaded audio resources from the list or select “Add a new one”, in case you want to use audios that have not yet been added to the project resources. |
| Громкость (volume) | Allows to set the volume of the audio resource. | Maximum values for the parameter: 1.000 - corresponds to sound volume set to 100%. |
| Panning | The distribution of the sound wave in the spatial range of the sound field, or, in other words, the distribution of sound on stereo channels (left, right, center). | By default, the value of this parameter is set to 0.000, that is, the sound is equally distributed between the stereo channels. To “shift” the sound to the left or to the right, the value of this parameter should be changed. Maximum values for the parameter: -1.000 - sound is fully shifted to the left 1.000 - the sound is fully shifted to the right |
| Режим проигрывания (playMode) | Allows to select the playback mode of the audio resource. | Possible values of the parameter when choosing the playback mode: once or repeat. |
| Decoding on the go | When this option is selected, the audio file is decoded and sent to RAM for playback in batches. |
Note
Decoding is the process of restoring the original form of presenting the information.
An audio file that is added to a project is initially encoded and consists of data packets. Before it is played, it will be decoded and fully loaded into RAM. However the decoded file weighs several times more than the encoded one which means that a 1MB audio file will take memory is much more space than 1 MB after decoding. This can be crucial when audio of large sizes (such as .flac) are used in the project.
However, it is possible to make decoding and sending to RAM for playing the file in batches. Thanks to the Live decoding feature it is possible to reduce the use of RAM and not fill it up with large audio files.
NOTE: remember that by freeing up RAM this way, the CPU is loaded by live decoding processes. In this case it is important to prioritize and decide what is of more importance: to free up RAM or not to load the CPU .
Events and actions of the objeсt AUDIO¶
| Action | Description |
|---|---|
| Установить аудио ресурс (setAudioResource) | Allows to set a new audio resource for playback. |
| Установить громкость (setVolume) | Allows to set a different playback volume than the one set in the properties of the object AUDIO. |
Pan |
Allows to change the distribution of the sound wave in the spatial range of the sound field, or, in other words, the distribution of sound on stereo channels (left, right, center). |
| Установить режим проигрывания (setPlayMode) | Allows to set a new audio resource playback mode: once or loop. |
-
параметр
Ресурс аудио;audioResource¶ The parameter allows to select an audio resource for a chosen object.
Note
Both a resource and a resource id can be assigned. See /articles/resources for details.
-
параметр
Громкость;volume¶ Allows to set the volume of the audio resource. The maximum volume corresponds to the value 1, silent playback - value 0. The default value is 1. See the Установить громкость (setVolume) action for details.
-
параметр
Режим воспроизведения;playMode¶ This parameter has two values: “once” and “loop”. The default value is “once”. For details, see action Проиграть (play), Установить аудио ресурс (setAudioResource)
-
действие
Установить аудио ресурс;setAudioResource(resource)¶ Set a new audio resource (parameter Ресурс аудио (audioResource)).
Parameters: Ресурс аудио / audioResource – The new audio resource to be exposed to the object. This call is equivalent to assigning the parameter Ресурс аудио (audioResource)
-
действие
Установить громкость;setVolume(volume)¶ Set a new volume for playing audio resources that is different from the one set in the properties of the object AUDIO (parameter Громкость (volume)).
Parameters: громкость / volume – New volume level.
-
действие
Установить режим проигрывания;setPlayMode(mode)¶ Set a new playback mode of the audio resource: once or **loop**(parameter Режим проигрывания (playMode)).
Parameters: Режим проигрывания / playMode – New play mode: ’once’ or ’loop’.
Events and actions of the object AUDIO (playback control)¶
Inserted into AudioReactor
| Event | Description |
|---|---|
| Запущен (onStart) | Called when the audio resource starts playing from the beginning. For example, to start the animation of the model along with the audio - this event will help to create this logic. |
| Остановлен (onStop) | Called when a user stops playing an audio resource. For example, to make sure that at the moment the audio is stopped by the user an image will appear on the screen - this event will help to create this logic. |
| Приостановлен (onPause) | Called when audio is paused. For example, to stop an animation of the model when the audio is paused, this event will help to create this logic. |
| Возобновлен (onResume) | Called when the audio is unpaused. For example, to resume the animation of the model when the audio is unpaused - this event will help to create this logic. |
| Завершён (onFinished) | Called when the audio has finished playing. For example, to show the text “THE END” on the screen when music stopped playing - this event will help to create this logic. |
| Action | Description |
|---|---|
| Проиграть (play) | Allows to start playing the installed audio resource. Audio always starts from the beginning |
| Остановить (stop) | Allows to stop playback and rewind the installed audio resource to the beginning. |
| Приостановить (pause) | Allows to pause the playback of the installed audio resource (pause playback). |
| Возобновить (resume) | Allows to resume playback of the installed audio resource from the point where it was paused (unpause). |
-
событие
Запущен;onStart()¶ Called when the audio resource starts playing from the beginning. When the Возобновить (resume) action is called, this event is not fired. See the Проиграть (play) action for details.
-
событие
Остановлен;onStop()¶ Called when the user stops playing an audio resource. This event is fired only when the Остановить (stop) action is called while the audio is playing.
-
событие
Приостановлен;onPause()¶ Called when the audio is paused. This event is fired only when the Приостановить (pause) action is called while the audio is playing.
-
событие
Возобновлён;onResume()¶ Called when the audio is unpaused. This event is fired only when the Возобновить (resume) action is called on paused audio.
-
событие
Завершён;onFinished()¶ Called when the audio resource finishes playing. When the Остановить (stop) action is called, this event is not fired.
-
действие
Проиграть;play(playMode = nil)¶ Start playing the audio resource from the beginning, regardless of the current state of the audio. When called, the Запущен (onStart) event comes.
If PlayMode / playMode is set to Once / once, then after the end of playback, the event Завершён (onFinished) will be called. If the playback mode is set to Loop / loop, then the playback will never end by itself, and, accordingly, the event will not be called. However, the playback mode can be changed explicitly with the Установить режим проигрывания (setPlayMode) action.
Parameters: Режим / playMode – Play mode: once - play once, loop - play in a loop. If the Studio is set to Do not change, the mode specified in the object’s parameters will be set.
Note
A call with playMode equal to nil will start playback with the play mode once or set manually before the call.
-
действие
Остановить;stop()¶ Stop playback and rewind the audio to the beginning. If the audio has not been started and is in its initial state, the action will not work. On a successful call, the Остановлен (onStop) event comes.
-
действие
Приостановить ;pause()¶ Pause audio playback. If the audio has not been started and is in its initial state, the action will not work. On a successful call, the Приостановлен (onPause) event comes.
Note
Even if the audio is already paused, calling the Приостановить (pause) action again will trigger the Приостановлен (onPause) event.
-
действие
Возобновить ;resume()¶ Continue playing the audio resource from where it was paused. If the audio has not been started and is in its initial state, the action will not work. On successful call, the Возобновлен (onResume) event comes.
Note
Even if audio is currently playing, calling the Возобновлен (onResume) action will cause the Возобновлен (onResume) event to be fired.