# Sound

## sound. Sound

This class handles sound playing (tones and tracks)

- If value is a number then a tone will be generated at that frequency in Hz.
- It value is a string, it must either be a note in the PsychoPy format (e.g 'A', 'Bfl', 'B', 'C', 'Csh'), in which case an octave must also be given, or the name of the resource track.

Note: the PsychoPy hamming parameter has not been implemented yet. It might be rather tricky to do so using Tone.js

## Constructor

#### new Sound(options)

Source:
  - sound/Sound.js, line 40

##### Example

    [...]
    const track = new Sound({
      win: psychoJS.window,
      value: 440,
      secs: 0.5
    });
    track.setVolume(1.0);
    track.play(2);

##### Parameters:

Name | Type | Description
--- | --- | ---
`options` | Object | ###### Properties
Name | Type | Attributes | Default | Description
--- | --- | --- | --- | ---
`name` | String |  |  | the name used when logging messages from this stimulus
`win` | module:core.Window |  |  | the associated Window
`value` | number | string | <optional> | `'C'` | the sound value (see above for a full description)
`octave` | number | <optional> | `4` | the octave corresponding to the tone (if applicable)
`secs` | number | <optional> | `0.5` | duration of the tone (in seconds) If secs == -1, the sound will play indefinitely.
`startTime` | number | <optional> | `0` | start of playback for tracks (in seconds)
`stopTime` | number | <optional> | `-1` | end of playback for tracks (in seconds)
`stereo` | boolean | <optional> | `true` | whether or not to play the sound or track in stereo
`volume` | number | <optional> | `1.0` | volume of the sound (must be between 0 and 1.0)
`loops` | number | <optional> | `0` | how many times to repeat the track or tone after it has played once. If loops == -1, the track or tone will repeat indefinitely until stopped.
`autoLog` | boolean | <optional> | `true` | whether or not to log

### Extends

- PsychObject

### Methods

#### (protected) _getPlayer() → {SoundPlayer}

Source:
  - sound/Sound.js, line 216

Identify the appropriate player for the sound.

##### Throws:

exception if no appropriate SoundPlayer could be found for the sound

Type
  Object.<string, *>

##### Returns:

the appropriate SoundPlayer

Type
  SoundPlayer

#### getDuration() → {number}

Source:
  - sound/Sound.js, line 127

Get the duration of the sound, in seconds.

##### Returns:

the duration of the sound, in seconds

Type
  number

#### play(loops, logopt)

Source:
  - sound/Sound.js, line 102

Start playing the sound.

Note: Sounds are played independently from the stimuli of the experiments, i.e. the experiment will not stop until the sound is finished playing. Repeat calls to play may results in the sounds being played on top of each other.

##### Parameters:

Name | Type | Attributes | Default | Description
--- | --- | --- | --- | ---
`loops` | number |  |  | how many times to repeat the sound after it plays once. If loops == -1, the sound will repeat indefinitely until stopped.
`log` | boolean | <optional> | `true` | whether or not to log

#### setLoops(loopsopt, logopt)

Source:
  - sound/Sound.js, line 183

Set the number of loops.

##### Parameters:

Name | Type | Attributes | Default | Description
--- | --- | --- | --- | ---
`loops` | number | <optional> | `0` | how many times to repeat the sound after it has played once. If loops == -1, the sound will repeat indefinitely until stopped.
`log` | boolean | <optional> | `true` | whether of not to log

#### setSecs(secsopt, logopt)

Source:
  - sound/Sound.js, line 199

Set the duration (in seconds)

##### Parameters:

Name | Type | Attributes | Default | Description
--- | --- | --- | --- | ---
`secs` | number | <optional> | `0.5` | duration of the tone (in seconds) If secs == -1, the sound will play indefinitely.
`log` | boolean | <optional> | `true` | whether or not to log

#### setSound(sound, logopt)

Source:
  - sound/Sound.js, line 155

Set the sound value on demand past initialisation.

##### Parameters:

Name | Type | Attributes | Default | Description
--- | --- | --- | --- | ---
`sound` | object |  |  | a sound instance to replace the current one
`log` | boolean | <optional> | `true` | whether or not to log

#### setVolume(volume, muteopt, logopt)

Source:
  - sound/Sound.js, line 139

Set the playing volume of the sound.

##### Parameters:

Name | Type | Attributes | Default | Description
--- | --- | --- | --- | ---
`volume` | number |  |  | the volume (values should be between 0 and 1)
`mute` | boolean | <optional> | `false` | whether or not to mute the sound
`log` | boolean | <optional> | `true` | whether of not to log

#### stop(options)

Source:
  - sound/Sound.js, line 114

Stop playing the sound immediately.

##### Parameters:

Name | Type | Description
--- | --- | ---
`options` | Object | ###### Properties
Name | Type | Attributes | Default | Description
--- | --- | --- | --- | ---
`log` | boolean | <optional> | `true` | whether or not to log