Libraries.Sound.AudioSamples Documentation

Inherits from: Libraries.Language.Object

Actions Documentation

Compare(Libraries.Language.Object object)

This action compares two object hash codes and returns an integer. The result is larger if this hash code is larger than the object passed as a parameter, smaller, or equal. In this case, -1 means smaller, 0 means equal, and 1 means larger. This action was changed in Quorum 7 to return an integer, instead of a CompareResult object, because the previous implementation was causing efficiency issues.

Parameters

Return

integer: The Compare result, Smaller, Equal, or Larger.

Example

Object o
Object t
integer result = o:Compare(t) //1 (larger), 0 (equal), or -1 (smaller)

Copy()

The Copy action returns a new AudioSamples object which contains the same samples as this AudioSamples, and which has the same number of channels and contains the same number of samples per second. All data stored in the copy is independent of the data in this AudioSamples, and can be changed without side effects.

Return

Libraries.Sound.AudioSamples: A copy of this AudioSamples object.

Example

use Libraries.Sound.AudioSamples

AudioSamples samples

// We load a file directly into our samples.
samples:Load("Chime.wav")

// This AudioSamples contains a copy of all sample information.
AudioSamples fullCopy = samples:Copy()

// This AudioSamples contains a copy of the first half of the samples.
AudioSamples halfCopy = samples:Copy(0, samples:GetSize() / 2)

// This AudioSamples contains a copy of the entire first channel.
AudioSamples channelCopy = samples:CopyChannel(0)

// This AudioSamples contains a copy of the first half of the first channel.
AudioSamples halfChannelCopy = samples:CopyChannel(0, 0, samples:GetSize() / 2)

Copy(integer first, integer last)

The Copy action returns a new AudioSamples object which contains a subset of the samples that are stored in this AudioSamples object. The new copy will contain the samples from all channels stored between the first and last indices given. All data stored in the copy is independent of the data in this AudioSamples and can be changed without side effects.

Parameters

  • integer first: The first sample index to be copied.
  • integer last: The last sample index to be copied.

Return

Libraries.Sound.AudioSamples: A copy of this AudioSamples containing the requested samples.

Example

use Libraries.Sound.AudioSamples

AudioSamples samples

// We load a file directly into our samples.
samples:Load("Chime.wav")

// This AudioSamples contains a copy of all sample information.
AudioSamples fullCopy = samples:Copy()

// This AudioSamples contains a copy of the first half of the samples.
AudioSamples halfCopy = samples:Copy(0, samples:GetSize() / 2)

// This AudioSamples contains a copy of the entire first channel.
AudioSamples channelCopy = samples:CopyChannel(0)

// This AudioSamples contains a copy of the first half of the first channel.
AudioSamples halfChannelCopy = samples:CopyChannel(0, 0, samples:GetSize() / 2)

CopyChannel(integer channel)

The CopyChannel action returns a new AudioSamples object which contains all of the samples stored in the requested channel. The copy will have only one channel, and will have the same samples per second as this AudioSamples. All data stored in the copy is independent of the data in this AudioSamples and can be changed without side effects.

Parameters

  • integer channel: Which channel to copy.

Return

Libraries.Sound.AudioSamples: A copy of this AudioSamples containing the requested channel.

Example

use Libraries.Sound.AudioSamples

AudioSamples samples

// We load a file directly into our samples.
samples:Load("Chime.wav")

// This AudioSamples contains a copy of all sample information.
AudioSamples fullCopy = samples:Copy()

// This AudioSamples contains a copy of the first half of the samples.
AudioSamples halfCopy = samples:Copy(0, samples:GetSize() / 2)

// This AudioSamples contains a copy of the entire first channel.
AudioSamples channelCopy = samples:CopyChannel(0)

// This AudioSamples contains a copy of the first half of the first channel.
AudioSamples halfChannelCopy = samples:CopyChannel(0, 0, samples:GetSize() / 2)

CopyChannel(integer channel, integer first, integer last)

The CopyChannel action returns a new AudioSamples object which contains a subset of the samples stored in the requested channel. The new copy will contain all samples between the first and last indices given that are in the requested channel. All data stored in the copy is independent of the data in this AudioSamples and can be changed without side effects.

Parameters

  • integer channel: Which channel to copy.
  • integer first: The first sample index to be copied.
  • integer last: The last sample index to be copied.

Return

Libraries.Sound.AudioSamples: A copy of this AudioSamples containing the requested samples from the requested channel.

Example

use Libraries.Sound.AudioSamples

AudioSamples samples

// We load a file directly into our samples.
samples:Load("Chime.wav")

// This AudioSamples contains a copy of all sample information.
AudioSamples fullCopy = samples:Copy()

// This AudioSamples contains a copy of the first half of the samples.
AudioSamples halfCopy = samples:Copy(0, samples:GetSize() / 2)

// This AudioSamples contains a copy of the entire first channel.
AudioSamples channelCopy = samples:CopyChannel(0)

// This AudioSamples contains a copy of the first half of the first channel.
AudioSamples halfChannelCopy = samples:CopyChannel(0, 0, samples:GetSize() / 2)

Equals(Libraries.Language.Object object)

This action determines if two objects are equal based on their hash code values.

Parameters

Return

boolean: True if the hash codes are equal and false if they are not equal.

Example

use Libraries.Language.Object
use Libraries.Language.Types.Text
Object o
Text t
boolean result = o:Equals(t)

Get(integer index)

The Get action returns the value of a single sample with in the AudioSamples. The value will be retrieved from the sample at the given index within the first channel (channel 0).

Parameters

  • integer index: The index to retrieve the value from.

Return

number: The sample value stored at the given index in channel 0.

Example

use Libraries.Sound.AudioSamples

AudioSamples samples

// We load a file directly into our samples.
samples:Load("Chime.wav")

integer counter = 0
repeat while counter < samples:GetSize()
    // We retrieve all the values from the first channel, divide
    // them by 2, then put them back.
    number value = samples:Get(counter) / 2
    samples:Set(counter, value)
    counter = counter + 1
end

Get(integer index, integer channel)

The Get action returns the value of a single sample within the AudioSamples. The value will be retrieved from the sample at the given index within the given channel.

Parameters

  • integer index: The index to retrieve the value from.
  • integer channel: Which channel the value should be retrieved from.

Return

number: The sample value stored at the given location.

Example

use Libraries.Sound.AudioSamples

AudioSamples samples

// We load a file directly into our samples.
samples:Load("Chime.wav")

integer counter = 0
repeat while counter < samples:GetSize()
    // We retrieve all the values from the first channel, divide
    // them by 2, then put them back.
    number value = samples:Get(counter, 0) / 2
    samples:Set(counter, value)
    counter = counter + 1
end

GetChannels()

The GetChannels action returns the number of channels that are currently being stored by this AudioSamples object.

Return

integer: The number of channels used by this AudioSamples object.

Example

use Libraries.Sound.AudioSamples

AudioSamples samples

// We load a file directly into our samples.
samples:Load("Chime.wav")

// We can now get some information back from our audio.
output "The samples has " + samples:GetChannels() + " channel(s)."
output "The samples has a playback rate of " + samples:GetSamplesPerSecond() + " samples per second."

GetHashCode()

This action gets the hash code for an object.

Return

integer: The integer hash code of the object.

Example

Object o
integer hash = o:GetHashCode()

GetSamplesPerSecond()

The GetSamplesPerSecond action returns the current playback rate the AudioSamples object. The default value is 44100.

Return

integer: The number of samples per second the AudioSamples stores.

Example

use Libraries.Sound.AudioSamples

AudioSamples samples

// We load a file directly into our samples.
samples:Load("Chime.wav")

// We can now get some information back from our audio.
output "The samples has " + samples:GetChannels() + " channel(s)."
output "The samples has a playback rate of " + samples:GetSamplesPerSecond() + " samples per second."

GetSize()

The GetSize action returns the number of samples that can be stored in each channel of the AudioSamples object.

Return

integer: The number of samples to store per channel in this AudioSamples object.

Example

use Libraries.Sound.AudioSamples

AudioSamples samples

// We load a file directly into our samples.
samples:Load("Chime.wav")

// We can now get some information back from our audio.
output "The samples has " + samples:GetChannels() + " channel(s)."
output "The samples has a playback rate of " + samples:GetSamplesPerSecond() + " samples per second."
output "The audio contains " + samples:GetSize() + " samples per channel."
output "The audio contains " + samples:GetTotalSize() + " samples total."
output "The audio lasts a total of " + samples:GetSizeInSeconds() + " seconds."

GetSizeInSeconds()

The GetSizeInSeconds action returns how many seconds of audio can be stored in this AudioSamples object.

Return

number: How many seconds of audio can be stored in this AudioSamples object.

Example

use Libraries.Sound.AudioSamples

AudioSamples samples

// We load a file directly into our samples.
samples:Load("Chime.wav")

// We can now get some information back from our audio.
output "The samples has " + samples:GetChannels() + " channel(s)."
output "The samples has a playback rate of " + samples:GetSamplesPerSecond() + " samples per second."
output "The audio contains " + samples:GetSize() + " samples per channel."
output "The audio contains " + samples:GetTotalSize() + " samples total."
output "The audio lasts a total of " + samples:GetSizeInSeconds() + " seconds."

GetTotalSize()

The GetTotalSize action returns the total number of samples that are stored in this AudioSamples object, across all channels.

Return

integer:

Example

use Libraries.Sound.AudioSamples

AudioSamples samples

// We load a file directly into our samples.
samples:Load("Chime.wav")

// We can now get some information back from our audio.
output "The samples has " + samples:GetChannels() + " channel(s)."
output "The samples has a playback rate of " + samples:GetSamplesPerSecond() + " samples per second."
output "The audio contains " + samples:GetSize() + " samples per channel."
output "The audio contains " + samples:GetTotalSize() + " samples total."
output "The audio lasts a total of " + samples:GetSizeInSeconds() + " seconds."

Load(Libraries.System.File file)

The Load action will retrieve samples from a sound file and store them in this AudioSamples object. This will also set the number of channels and the samples per second. The supported file types are Ogg and 16-bit WAV.

Parameters

  • Libraries.System.File: The file to load into this AudioSamples. use Libraries.Sound.AudioSamples use Libraries.System.File AudioSamples samples // We load a file directly into our samples. File file file:SetPath("Chime.wav") samples:Load(file) // We can now get some information back from our audio. output "The samples has " + samples:GetChannels() + " channel(s)." output "The samples has a playback rate of " + samples:GetSamplesPerSecond() + " samples per second." output "The audio contains " + samples:GetSize() + " samples per channel." output "The audio contains " + samples:GetTotalSize() + " samples total." output "The audio lasts a total of " + samples:GetSizeInSeconds() + " seconds."

Load(text filePath)

The Load action will retrieve samples from a sound file located at the given relative path from the program's default working directory and store them in this AudioSamples object. This will also set the number of channels and the samples per second. The supported file types are Ogg and 16-bit WAV.

Parameters

  • text filePath: The relative path to a sound file to load into this AudioSamples.

Example

use Libraries.Sound.AudioSamples

AudioSamples samples

// We load a file directly into our samples.
samples:Load("Chime.wav")

// We can now get some information back from our audio.
output "The samples has " + samples:GetChannels() + " channel(s)."
output "The samples has a playback rate of " + samples:GetSamplesPerSecond() + " samples per second."
output "The audio contains " + samples:GetSize() + " samples per channel."
output "The audio contains " + samples:GetTotalSize() + " samples total."
output "The audio lasts a total of " + samples:GetSizeInSeconds() + " seconds."

Set(integer index, number value, integer channel)

The Set action sets the value of a single sample within the AudioSamples. The provided index should be between 0 and the size per channel of the object, which is provided by the GetSize() action. The given value should be between -1 and 1. The value will be stored as part of the indicated channel.

Parameters

  • integer index: The index of the sample to be set.
  • number value: The value of the sample, between -1 and 1.
  • integer channel: Which channel of the AudioSamples to set.

Example

use Libraries.Sound.Audio
use Libraries.Sound.AudioSamples
use Libraries.Compute.Random

AudioSamples samples

// We set the number of channels and samples per second before setting the size of the samples.
samples:SetChannels(2)
samples:SetSamplesPerSecond(44100)
samples:SetSizeInSeconds(2)

// We create white noise using random numbers.
integer counter = 0
Random random
repeat while counter < samples:GetSize()
    number value = random:RandomNumber() * 2 - 1
    samples:Set(counter, value, 0)
    samples:Set(counter, -1 * value, 1)
    counter = counter + 1
end

// We can now load and play the audio.
Audio audio
audio:Load(samples)
audio:PlayUntilDone()

Set(integer index, number value)

The Set action sets the value of a single sample within the AudioSamples. The provided index should be between 0 and the size per channel of the object, which is provided by the GetSize() action. The given value should be between -1 and 1. The value will be set at the index of the first channel (channel 0).

Parameters

  • integer index: The index of the sample to be set.
  • number value: The value of the sample, between -1 and 1.

Example

use Libraries.Sound.Audio
use Libraries.Sound.AudioSamples
use Libraries.Compute.Random

AudioSamples samples

// We set the number of channels and samples per second before setting the size of the samples.
samples:SetChannels(1)
samples:SetSamplesPerSecond(44100)
samples:SetSizeInSeconds(2)

// We create white noise using random numbers.
integer counter = 0
Random random
repeat while counter < samples:GetSize()
    number value = random:RandomNumber() * 2 - 1
    samples:Set(counter, value)
    counter = counter + 1
end

// We can now load and play the audio.
Audio audio
audio:Load(samples)
audio:PlayUntilDone()

SetChannels(integer channels)

The SetChannels action sets the number of channels to be stored in this AudioSamples object. This should be used before calling the SetSize or SetSizeInSeconds actions. If the AudioSamples are copied or loaded from a file, then this will be set automatically.

Parameters

  • integer channels: The number of channels to store samples for.

Example

use Libraries.Sound.Audio
use Libraries.Sound.AudioSamples
use Libraries.Compute.Random

AudioSamples samples

// We set the number of channels and samples per second before setting the size of the samples.
samples:SetChannels(1)
samples:SetSamplesPerSecond(44100)
samples:SetSizeInSeconds(2)

// We create white noise using random numbers.
integer counter = 0
Random random
repeat while counter < samples:GetSize()
    number value = random:RandomNumber() * 2 - 1
    samples:Set(counter, value)
    counter = counter + 1
end

// We can now load and play the audio.
Audio audio
audio:Load(samples)
audio:PlayUntilDone()

SetSamplesPerSecond(integer samples)

The SetSamplesPerSecond action determines how many samples should be used for each second of audio when the AudioSamples are used, e.g. by the Audio class. The default value is 44100.

Parameters

  • integer samples: The number of samples per second the AudioSamples stores.

Example

use Libraries.Sound.Audio
use Libraries.Sound.AudioSamples
use Libraries.Compute.Random

AudioSamples samples

// We set the number of channels and samples per second before setting the size of the samples.
samples:SetChannels(1)
samples:SetSamplesPerSecond(44100)
samples:SetSizeInSeconds(2)

// We create white noise using random numbers.
integer counter = 0
Random random
repeat while counter < samples:GetSize()
    number value = random:RandomNumber() * 2 - 1
    samples:Set(counter, value)
    counter = counter + 1
end

// We can now load and play the audio.
Audio audio
audio:Load(samples)
audio:PlayUntilDone()

SetSize(integer samples)

The SetSize action stores the number of samples that may be stored in each channel of the AudioSamples object. Before using this action, the number of channels should already have been set using SetChannels().

Parameters

  • integer samples: The number of samples to store per channel in this AudioSamples object.

Example

use Libraries.Sound.Audio
use Libraries.Sound.AudioSamples
use Libraries.Compute.Random

AudioSamples samples

// We set the number of channels and samples per second before setting the size of the samples.
samples:SetChannels(1)
samples:SetSamplesPerSecond(44100)
samples:SetSize(88200)

// We create white noise using random numbers.
integer counter = 0
Random random
repeat while counter < samples:GetSize()
    number value = random:RandomNumber() * 2 - 1
    samples:Set(counter, value)
    counter = counter + 1
end

// We can now load and play the audio.
Audio audio
audio:Load(samples)
audio:PlayUntilDone()

SetSizeInSeconds(number seconds)

The SetSizeInSeconds action sets the storage size of the AudioSamples to hold enough samples for the given number of seconds of audio. Before setting the size of the AudioSamples with this action, the number of channels and samples per second should already have been set with SetChannels() and SetSamplesPerSecond(), respectively.

Parameters

  • number seconds: How many seconds of audio should be able to be stored in this AudioSamples object.

Example

use Libraries.Sound.Audio
use Libraries.Sound.AudioSamples
use Libraries.Compute.Random

AudioSamples samples

// We set the number of channels and samples per second before setting the size of the samples.
samples:SetChannels(1)
samples:SetSamplesPerSecond(44100)
samples:SetSizeInSeconds(2)

// We create white noise using random numbers.
integer counter = 0
Random random
repeat while counter < samples:GetSize()
    number value = random:RandomNumber() * 2 - 1
    samples:Set(counter, value)
    counter = counter + 1
end

// We can now load and play the audio.
Audio audio
audio:Load(samples)
audio:PlayUntilDone()

SetTotalSize(integer samples)

The SetTotalSize action sets the total number of samples that may be stored in this AudioSamples object, across all channels. The provided integer should be a multiple of the number of channels used.

Parameters

  • integer samples: The total number of samples to store in this AudioSamples object.

Example

use Libraries.Sound.Audio
use Libraries.Sound.AudioSamples
use Libraries.Compute.Random

AudioSamples samples

// We set the number of channels and samples per second before setting the size of the samples.
samples:SetChannels(2)
samples:SetSamplesPerSecond(44100)
samples:SetTotalSize(88200)

// We create white noise using random numbers.
integer counter = 0
Random random
repeat while counter < samples:GetSize()
    number value = random:RandomNumber() * 2 - 1
    samples:Set(counter, value, 0)
    samples:Set(counter, -1 * value, 1)
    counter = counter + 1
end

// We can now load and play the audio.
Audio audio
audio:Load(samples)
audio:PlayUntilDone()