====== assets.audio (ExportAudio) (Control audio) ======
\\
\\
ExportAudio is added after the audio related functions in [[en:vci:script:reference:exportassets | ExportAssets]].\\
Audio related functions in [[en:vci:script:reference:exportassets | ExportAssets]] is left as is for the sake of backward compatibility.\\

----

===== List of functions =====

**For the latest list of the functions, refer to "types.lua" file in the "EmbeddedScriptWorkspace" folder. **

^ Function ^ Description ^
| Play | Play the AudioClip specified with a file name.\\ You can specify the volume and the loop.\\ |
| PlayFromIndex | Play the AudioClip specified with an index number.\\ You can specify the volume and the loop.\\ |
| PlayOneShot | Play the AudioClip specified with file name once.\\ You can only specify the volume, no looping.\\ |
| PlayOneShotFromIndex | Play the AudioClip specified with an index number once.\\ You can only specify the volume, no looping.\\ |
| Stop | Stop the playback of the AudioClip specified with a file name. |
| StopFromIndex | Stop the playback of the AudioClip specified with an index number. |
| Pause | Pause the playback of the AudioClip specified with a file name.\\ |
| PauseFromIndex | Pause the playback of the AudioClip specified with an index number. |

The functions with ''_ALL_'' are synchronized and run on other clients as well.\\
If you want the result to be the same in all clients, use functions with ''_ALL_'' prefix.

^ Function ^ Description ^
| _ALL_Play | Play the AudioClip specified with a file name.\\ You can specify the volume and the loop.\\ |
| _ALL_PlayFromIndex | Play the AudioClip specified with an index number.\\ You can specify the volume and the loop.\\ |
| _ALL_PlayOneShot | Play the AudioClip specified with file name once.\\ You can only specify the volume, no looping.\\ |
| _ALL_PlayOneShotFromIndex | Play the AudioClip specified with index number once.\\ You can only specify the volume, no looping.\\ |
| _ALL_Stop | Stop the playback of the AudioClip specified with a file name. |
| _ALL_StopFromIndex | Stop the playback of the AudioClip specified with an index number. |
| _ALL_Pause | Pause the playback of the AudioClip specified with a file name.\\ |
| _ALL_PauseFromIndex | Pause the playback of the AudioClip specified with an index number. |

----

===== Synchronization of VCI =====

When you are creating something that moves over a network, you have to take the synchronization into account.\\
In a scenario where there are three people (A, B and C) in a single Virtual Cast studio, the act of applying the result of person A moving an object to the computer of person B and C is called "synchronization."\\
On the other hand, when something moves only in the computer of the person who moved it, that situation is called "working in local only."\\
Following are the most common way of synchronization in VCI.\\

  * Transform is synchronized by Virtual Cast feature.\\
  * Functions with ''_ALL_'' will be synchronized and run.\\
  * Use [[en/vci/script/reference/syncvariable|sync variables]] to sync the state of VCIs.\\

Basically, use the functions with ''_ALL_'' so that the VCI behaves the same in every user's clients.\\
* For simple VCIs, such as the one that plays a sound, you can just call ''_ALL_'' in an event function.\\
On the other hand, if you want everyone's VCIs to have varying states, make them run locally so that the states won't be synchronized.\\
\\
For details on the synchronization of transform, refer to [[en:vci:component:sdk:subitem:owned|About VCI items and subitems]].\\

----

===== AudioIndex =====

{{:en:vci:script:reference:exportassets:audioindex.jpg?direct&400|}}\\

  * You can specify the audio with either file name or AudioIndex.
  * AudioIndex is registered from the top of the hierarchy.
  * The index number starts from 0.
  * In the image above: On the item AudioTest_1, specifying index0 will play Audio1.\\ On the item AudioTest_2, specifying index0 will play Audio5.

----

===== Play() =====

**1st argument: AudioClip name (String) 2nd argument: volume (number) 3rd argument: loop setting (bool)**

  * You must specify all arguments. You cannot omit any.
  * Use the name of the audio file attached as the AudioClip on the AudioSource.
  * The volume is to be specified with a number between 0 and 1. The value that surpasses 1 will be handled as 1.

Example\\
<file lua main.lua>
function onUse()
    -- loop play the audio if true. Play one-shot if false
    local audioLoop = true

    -- Specify the volume with a value between 0 and 1
    local audioVolume = 0.5

    -- Loop play "Audio1"
    vci.assets.audio._ALL_Play("Audio1", audioVolume, audioLoop)
end

function onUnuse()
    --Stop playing "Audio1"
    vci.assets.audio._ALL_Stop("Audio1")
end
</file>

The result\\
<code lua>
(When used, loop play the "Audio1" with a volume of 0.5.)
(Stop playing "Audio1" when unused.)
</code>

----

===== PlayFromIndex() =====

**1st argument: index number (number) 2nd argument: volume (number) 3rd argument: loop setting (bool)**

  * You must specify all arguments. You cannot omit any.
  * Specify audio with the number of AudioIndex.\\ For the detail on how the index number is assigned, refer to [[en:vci:script:reference:exportassets:audio#audioindex |this article]].
  * The volume is to be specified with a number between 0 and 1. The value that surpasses 1 will be handled as 1.

Example\\
<file lua main.lua>
function onUse()
    -- loop play the audio if true. Play one-shot if false
    local audioLoop = true

    -- Specify the volume with a value between 0 and 1
    local audioVolume = 0.5

    -- Loop play the AudioIndex0
    vci.assets.audio._ALL_PlayFromIndex(0, audioVolume, audioLoop)
end

function onUnuse()
    --Stop playing AudioIndex0
    vci.assets.audio._ALL_StopFromIndex(0)
end
</file>

The result\\
<code lua>
(When used, loop play the AudioIndex0 with a volume of 0.5.)
(Stop playing AudioIndex0 when unused.)
</code>

----

===== PlayOneShot() =====

**1st argument: AudioClip name (string) 2nd argument: volume (number)**

  * Use the name of the audio file attached as the AudioClip on the AudioSource.
  * The volume is to be specified with a number between 0 and 1. The value that surpasses 1 will be handled as 1.

Example\\
<file lua main.lua>
function onUse()
    -- Specify the volume with a value between 0 and 1
    local audioVolume = 0.5

    -- Loop play "Audio1"
    vci.assets.audio._ALL_PlayOneShot("Audio1", audioVolume)
end
</file>

The result\\
<code lua>
(When used, play once the "Audio1" with a volume of 0.5.)
</code>

----

===== PlayOneShotFromIndex() =====

**1st argument: index number (number) 2nd argument: volume (number)**

  * Specify audio with the number of AudioIndex.\\ For the detail on how the index number is assigned, refer to [[en:vci:script:reference:exportassets:audio#audioindex |this article]].
  * The volume is to be specified with a number between 0 and 1. The value that surpasses 1 will be handled as 1.

Example\\
<file lua main.lua>
function onUse()
    -- Specify the volume with a value between 0 and 1
    local audioVolume = 0.5

    -- Loop play the AudioIndex0
    vci.assets.audio._ALL_PlayOneShotFromIndex(0, audioVolume)
end
</file>

The result\\
<code lua>
(When used, play once the AudioIndex0 with a volume of 0.5.)
</code>

----

===== Stop() =====

**1st argument: AudioClip name (string)**

  * Use the name of the audio file attached as the AudioClip on the AudioSource.

Example\\
<file lua main.lua>
function onUse()
    -- Loop play "Audio1"
    vci.assets.audio._ALL_Play("Audio1", 0.5, true)
end

function onUnuse()
    --Stop playing "Audio1"
    vci.assets.audio._ALL_Stop("Audio1")
end
</file>

The result\\
<code lua>
(When used, loop play the "Audio1" with a volume of 0.5.)
(Stop playing "Audio1" when unused.)
</code>

----

===== StopFromIndex() =====

**1st argument: index number (number)**

  * Specify audio with the number of AudioIndex.\\ For the detail on how the index number is assigned, refer to [[en:vci:script:reference:exportassets:audio#audioindex |this article]].

Example\\
<file lua main.lua>
function onUse()
    -- Loop play the AudioIndex0
    vci.assets.audio._ALL_PlayFromIndex(0, 0.5, true)
end

function onUnuse()
    --Stop playing AudioIndex0
    vci.assets.audio._ALL_StopFromIndex(0)
end
</file>

The result\\
<code lua>
(When used, loop play the AudioIndex0 with a volume of 0.5.)
(Stop playing AudioIndex0 when unused.)
</code>

----


===== Pause() =====

**1st argument: AudioClip name (string) 2nd argument: stop/play (bool)**

  * Use the name of the audio file attached as the AudioClip on the AudioSource.
  * If true, pauses the audio playback.\\ If false, resume the paused audio.\\

Example\\
<file lua main.lua>
-- Loop play "Audio1"
vci.assets.audio._ALL_Play("Audio1", 0.5, true)


function onUse()
    -- Pause the playback of "Audio1"
    vci.assets.audio._ALL_Pause("Audio1", true)
end

function onUnuse()
    -- Cancel the pause of "Audio1" and resume the playback
    vci.assets.audio._ALL_Pause("Audio1", false)
end
</file>

The result\\
<code lua>
(When the VCI is spawned, loop playback of "Audio1" starts.)
(Pauses "Audio1" when used.)
(Resume the playback of "Audio1" from the paused point when unused.)
</code>

----

===== PauseFromIndex() =====

**1st argument: index number (number) 2nd argument: stop/play (bool)**

  * Specify audio with the number of AudioIndex.\\ For the detail on how the index number is assigned, refer to [[en:vci:script:reference:exportassets:audio#audioindex |this article]].
  * If true, pauses the audio playback.\\ If false, resume the paused audio.\\

Example\\
<file lua main.lua>
-- Loop play the AudioIndex0
vci.assets.audio._ALL_PlayFromIndex(0, 0.5, true)


function onUse()
    -- Pause the playback of AudioIndex0
    vci.assets.audio._ALL_PauseFromIndex(0, true)
end

function onUnuse()
    -- Cancel the pause of AudioIndex0 and resume the playback
    vci.assets.audio._ALL_PauseFromIndex(0, false)
end
</file>

The result\\
<code lua>
(When the VCI is spawned, loop playback of AudioIndex0 starts.)
(Pauses AudioIndex0 when used.)
(Resume the playback of AudioIndex0 from the paused point when unused.)
</code>