Name
PlaySample -- start playing a sample
Synopsis
PlaySample(id[, table], ...)
Function
Starts playing the sample specified by id. You can load samples either using the LoadSample() command or by using the @SAMPLE preprocessor command (the sample will be preloaded then).

Starting with Hollywood 2.0, you can also pass a table as the second argument that defines parameters for the sample playback. The table can contain the following fields:

Times:
This field can be used to specify how many times the sample shall be played. This defaults to 1 which means that the sample will be played once. If you want the sample to loop infinitely, set Times to 0.

Volume:
Set this to the desired playback volume. This field can range from 0 to 64. If not specified, the sample's default volume will be used (you can modify the default volume of a sample by calling SetVolume()).

Pitch:
Set this to the desired playback pitch. This value has to be passed in hertz. If not specified, the sample's default pitch will be used (you can modify the default pitch of a sample by calling SetPitch()).

Time:
This field can be used to define how long the sample shall be played. Hollywood will loop the sample until the given time has elapsed. Time must be specified in milliseconds. This tag is mutually exclusive with the Times tag.

Panning:
This field allows you to set the channel panning for this sample. This must be in the range of 0 to 255. 0 means left speaker playback only, 128 means both speakers, and 255 means right speaker only. If not specified, the sample's default pan setting will be used (you can modify the default panning of a sample by calling SetPanning()). (V4.5)

Channel:
Channel to use for playback of this sample. By default, PlaySample() will automatically choose a vacant channel and will fail if there is no vacant channel. To override this behaviour, you can use this field. When specified, it will always enforce playback on the very channel specified here. If the channel is already playing, it will be stopped first. (V6.1)

Also new in Hollywood 2.0 is the possibility to play multiple samples at once with one call to PlaySample(). Simply repeat the argument list as many times as you like and PlaySample() will play all specified samples together - perfectly synchronized. Please note that for each additional sample there is also an additional optional argument, that either specifies the number of times the sample shall be played or it is a table that contains further attributes for the sample playback. See above for all possibilities.

Inputs
id
identifier of sample to play
table
a table that contains playback parameters for the sample (V2.0)
...
the argument list can be repeated as many times as you like; PlaySample() will start all samples at the same time if you specify more than one
Example
PlaySample(1)
The above code starts playing sample 1. The sample will not be looped. 

PlaySample(1, {Time = 10000})
The code above plays sample 1 for exactly 10 seconds (= 10000 milliseconds). 

PlaySample(1, {Times = 2}, 2, {Times = 4}, 3, {Time=5000})
The code above plays sample 1 two times, sample 2 four times and sample 3 is played for 5 seconds. All three samples are started at once.
Show TOC