Difference between revisions of "Oolite JavaScript Reference: SoundSource"
(New page: <small>'''Prototype:''' <code>Object</code></small><br /> <small>'''Subtypes:''' none {{Oolite-class-added|1.71}} A '''SoundSource''' is an abstract object that can play a sound. A given...) |
(Updating BB links) |
||
| (10 intermediate revisions by 5 users not shown) | |||
| Line 1: | Line 1: | ||
<small>'''Prototype:''' <code>Object</code></small><br /> | <small>'''Prototype:''' <code>Object</code></small><br /> | ||
| − | <small>'''Subtypes:''' none | + | <small>'''Subtypes:''' none</small> |
| − | |||
| − | |||
A '''SoundSource''' is an abstract object that can play a sound. A given <code>SoundSource</code> can only be playing one sound at a particular time. | A '''SoundSource''' is an abstract object that can play a sound. A given <code>SoundSource</code> can only be playing one sound at a particular time. | ||
| Line 8: | Line 6: | ||
=== Sound Expressions === | === Sound Expressions === | ||
Several <code>SoundSource</code> properties and methods can take either <code>Sound</code> object, or a string representing a file name or a [[customsounds.plist]] key. | Several <code>SoundSource</code> properties and methods can take either <code>Sound</code> object, or a string representing a file name or a [[customsounds.plist]] key. | ||
| + | |||
| + | == Constructor == | ||
| + | '''new SoundSource''' : SoundSource | ||
| + | Creates a new SoundSource that can be altered. e.g.: | ||
| + | var mySound = new SoundSource; | ||
| + | mySound.sound = "trumblesqueal.ogg"; | ||
| + | mySound.loop = true; | ||
| + | mySound.play(); | ||
| + | |||
== Properties == | == Properties == | ||
| Line 19: | Line 26: | ||
'''See Also:''' <code>[[#repeatCount|repeatCount]]</code> | '''See Also:''' <code>[[#repeatCount|repeatCount]]</code> | ||
| + | |||
| + | === <code>position</code> === | ||
| + | {{oolite-prop-added|1.79}} | ||
| + | '''position''' : Vector (read/write) | ||
| + | The position of the sound source relative to the listener. The listener is always positioned at the origin facing along the Z axis. Therefore if the sound relates to something outside the spaceship, it will need to be positioned relatively to the player. | ||
| + | |||
| + | === <code>positional</code> === | ||
| + | {{oolite-prop-added|1.79}} | ||
| + | '''positional''' : Boolean (read/write) | ||
| + | Whether the SoundSource is positional at all. Non-positional sound sources are "positioned" at the origin. | ||
| + | |||
| + | Note that a SoundSource playing a sound with stereo information built-in is effectively non-positional. | ||
=== <code>repeatCount</code> === | === <code>repeatCount</code> === | ||
| Line 28: | Line 47: | ||
=== <code>sound</code> === | === <code>sound</code> === | ||
'''sound''' : [[#Sound Expressions|soundExpression]] (read/write) | '''sound''' : [[#Sound Expressions|soundExpression]] (read/write) | ||
| − | The sound to be played by this sound source. You can assign either a <code>[[Oolite JavaScript Reference: Sound]]</code> or a string to this property, but when you read it it will always be a <code>[[Oolite JavaScript Reference: Sound]]</code> object (or <code>null</code>). | + | The sound to be played by this sound source. You can assign either a <code>[[Oolite JavaScript Reference: Sound|Sound]]</code> or a string to this property, but when you read it it will always be a <code>[[Oolite JavaScript Reference: Sound|Sound]]</code> object (or <code>null</code>). |
| + | === <code>volume</code> === | ||
| + | {{oolite-prop-added|1.79}} | ||
| + | '''volume''' : Number (read/write) | ||
| + | The relative volume of the sound source, between 0.0 and 1.0, with 1.0 being the loudest possible and the default. This is further modified of course by the global volume set by the player in their preferences. | ||
== Methods == | == Methods == | ||
=== <code>play</code> === | === <code>play</code> === | ||
| − | play([count : Integer]) | + | function '''play'''([count : Integer]) |
Start playing <code>[[#sound|sound]]</code>. If <code>count</code> is specified, <code>[[#repeatCount|repeatCount]]</code> is set to <code>count</code> first. If the sound source is currently playing a sound, it is stopped. | Start playing <code>[[#sound|sound]]</code>. If <code>count</code> is specified, <code>[[#repeatCount|repeatCount]]</code> is set to <code>count</code> first. If the sound source is currently playing a sound, it is stopped. | ||
| Line 39: | Line 62: | ||
=== <code>playOrRepeat</code> === | === <code>playOrRepeat</code> === | ||
| − | playOrRepeat() | + | function '''playOrRepeat'''() |
If a sound is not playing, starts playing. If a sound is playing and is not looping, increases [[#repeatCount|repeatCount]] by one. | If a sound is not playing, starts playing. If a sound is playing and is not looping, increases [[#repeatCount|repeatCount]] by one. | ||
| Line 45: | Line 68: | ||
=== <code>playSound</code> === | === <code>playSound</code> === | ||
| − | + | function '''playSound'''(sound : [[#Sound Expressions|soundExpression]] [, count : Integer]) | |
| − | Set <code>[[#sound|sound]]</code> (and, optionally, [[#repeatCount|repeatCount]]) and start playing. | + | Set <code>[[#sound|sound]]</code> (and, optionally, <code>[[#repeatCount|repeatCount]]</code>) and start playing. |
'''See Also:''' <code>[[#play|play]]()</code> | '''See Also:''' <code>[[#play|play]]()</code> | ||
=== <code>stop</code> === | === <code>stop</code> === | ||
| − | stop() | + | function '''stop'''() |
Stop playing sound. | Stop playing sound. | ||
| + | |||
| + | == Links == | ||
| + | *[https://bb.oolite.space/viewtopic.php?f=4&t=7984 How many times to play the sound?] (2010) | ||
| − | [[Category:Oolite | + | [[Category:Oolite JavaScript Reference]] |
Latest revision as of 02:19, 29 February 2024
Prototype: Object
Subtypes: none
A SoundSource is an abstract object that can play a sound. A given SoundSource can only be playing one sound at a particular time.
Contents
Sound Expressions
Several SoundSource properties and methods can take either Sound object, or a string representing a file name or a customsounds.plist key.
Constructor
new SoundSource : SoundSource
Creates a new SoundSource that can be altered. e.g.:
var mySound = new SoundSource; mySound.sound = "trumblesqueal.ogg"; mySound.loop = true; mySound.play();
Properties
isPlaying
isPlaying : Boolean (read-only)
true if the sound is currently playing, false otherwise.
loop
loop : Boolean (read/write)
true if the sound source should loop its sound, false otherwise. Changing this while a sound is playing does not affect the currently-playing sound; it only takes effect when the sound source starts playing.
See Also: repeatCount
position
This property was added in Oolite test release 1.79.
position : Vector (read/write)
The position of the sound source relative to the listener. The listener is always positioned at the origin facing along the Z axis. Therefore if the sound relates to something outside the spaceship, it will need to be positioned relatively to the player.
positional
This property was added in Oolite test release 1.79.
positional : Boolean (read/write)
Whether the SoundSource is positional at all. Non-positional sound sources are "positioned" at the origin.
Note that a SoundSource playing a sound with stereo information built-in is effectively non-positional.
repeatCount
repeatCount : Integer (read/write)
The number of times the sound should repeat, if loop is false, ranging from 1 to 100. Unlike loop, this can usefully be changed while the sound is playing, and repeatCount will be decremented each time the sound is repeated.
See Also: loop
sound
sound : soundExpression (read/write)
The sound to be played by this sound source. You can assign either a Sound or a string to this property, but when you read it it will always be a Sound object (or null).
volume
This property was added in Oolite test release 1.79.
volume : Number (read/write)
The relative volume of the sound source, between 0.0 and 1.0, with 1.0 being the loudest possible and the default. This is further modified of course by the global volume set by the player in their preferences.
Methods
play
function play([count : Integer])
Start playing sound. If count is specified, repeatCount is set to count first. If the sound source is currently playing a sound, it is stopped.
See Also: playOrRepeat(), playSound()
playOrRepeat
function playOrRepeat()
If a sound is not playing, starts playing. If a sound is playing and is not looping, increases repeatCount by one.
See Also: play()
playSound
function playSound(sound : soundExpression [, count : Integer])
Set sound (and, optionally, repeatCount) and start playing.
See Also: play()
stop
function stop()
Stop playing sound.
