Libraries.Sound.AudioSamples Documentation

Inherits from: Libraries.Language.Object

Summary

Actions Summary Table

ActionsDescription
Compare(Libraries.Language.Object object)This action compares two object hash codes and returns a CompareResult.
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.
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.
CopyChannel(integer channel)The CopyChannel action returns a new AudioSamples object which contains all of the samples stored in the requested channel.
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.
Equals(Libraries.Language.Object object)This action determines if two objects are equal based on their hash code values.
Get(integer index)The Get action returns the value of a single sample with in the AudioSamples.
Get(integer index, integer channel)The Get action returns the value of a single sample within the AudioSamples.
GetChannels()The GetChannels action returns the number of channels that are currently being stored by this AudioSamples object.
GetHashCode()This action gets the hash code for an object.
GetSamplesPerSecond()The GetSamplesPerSecond action returns the current playback rate the AudioSamples object.
GetSize()The GetSize action returns the number of samples that can be stored in each channel of the AudioSamples object.
GetSizeInSeconds()The GetSizeInSeconds action returns how many seconds of audio can be stored in this AudioSamples object.
GetTotalSize()The GetTotalSize action returns the total number of samples that are stored in this AudioSamples object, across all channels.
Load(Libraries.System.File file)The Load action will retrieve samples from a sound file and store them in this AudioSamples object.
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.
Set(integer index, number value, integer channel)The Set action sets the value of a single sample within the AudioSamples.
Set(integer index, number value)The Set action sets the value of a single sample within the AudioSamples.
SetChannels(integer channels)The SetChannels action sets the number of channels to be stored in this AudioSamples object.
SetSamplesPerSecond(integer samples)The SetSamplesPerSecond action determines how many samples should be used for each second of audio when the AudioSamples are used, e.
SetSize(integer samples)The SetSize action stores the number of samples that may be stored in each channel of the AudioSamples object.
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.
SetTotalSize(integer samples)The SetTotalSize action sets the total number of samples that may be stored in this AudioSamples object, across all channels.

Actions Documentation

Compare(Libraries.Language.Object object)

This action compares two object hash codes and returns a CompareResult. The compare result is either larger if this hash code is larger than the object passed as a parameter, smaller, or equal.

Example Code

use Libraries.Language.Support.CompareResult
        Object o
        Object t
        CompareResult result = o:Compare(t)

Parameters

Return

Libraries.Language.Support.CompareResult: The Compare result, Smaller, Equal, or Larger.

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.

Example Code

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)

Return

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

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.

Example Code

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)

Parameters

Return

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

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.

Example Code

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)

Parameters

Return

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

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.

Example Code

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)

Parameters

Return

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

Equals(Libraries.Language.Object object)

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

Example Code

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

Parameters

Return

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

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).

Example Code

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

Parameters

Return

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

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.

Example Code

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

Parameters

Return

number: The sample value stored at the given location.

GetChannels()

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

Example Code

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."

Return

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

GetHashCode()

This action gets the hash code for an object.

Example Code

Object o
        integer hash = o:GetHashCode()

Return

integer: The integer hash code of the object.

GetSamplesPerSecond()

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

Example Code

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."

Return

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

GetSize()

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

Example Code

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."

Return

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

GetSizeInSeconds()

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

Example Code

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."

Return

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

GetTotalSize()

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

Example Code

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."

Return

integer:

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

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.

Example Code

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."

Parameters

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.

Example Code

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()

Parameters

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).

Example Code

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()

Parameters

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.

Example Code

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()

Parameters

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.

Example Code

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()

Parameters

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().

Example Code

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()

Parameters

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.

Example Code

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()

Parameters

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.

Example Code

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()

Parameters