Libraries.Sound.AudioSamples

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.

Example Code

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

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)

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)

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)

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)

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)

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

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

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

This action gets the hash code for an object.

Example Code

Object o
        integer hash = o:GetHashCode()

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

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

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

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

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.

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

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

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

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

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

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

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

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