gensound.sound

The module of Sound class for handling sound

class gensound.sound.Sound(data: <built-in function array>, samplerate: float) → None

Bases: object

The class for handling sound

Parameters:

• data (<built-in function array>) – Sound data array. First dimension is time, second dimension is channel. Will clipping if value were out of -1.0 to 1.0.
• samplerate (float) – Sampling rate of sound data.

Raises:

• ValueError – Data was invalid dimensions.
• InvalidSamplerateError – Samplerate was 0 or less.
• InvalidDurationError – Data was empty.

classmethod from_sinwave(frequency, duration=1.0, volume=1.0, samplerate=44100, smooth_end=True)

Generate sine wave sound

Parameters:

• frequency (float) – Frequency of new sound.
• duration (float) – Duration in seconds of new sound.
• volume (float) – The volume of new sound.
• samplerate (float) – Sampling rate of new sound.
• smooth_end (bool) – Do make smooth end or not. Please see above.

Return type:

Sound

Returns:

A new Sound instance.

Raises:

• InvalidDurationError – Duration was 0 or less.
• InvalidFrequencyError – Frequency was 0 or less.
• InvalidSamplerateError – Samplerate was 0 or less.
• InvalidVolumeError – Volume was lower than 0.0 or higher than 1.0.

This example makes 440Hz sine wave sound.

>>> sound = Sound.from_sinwave(440)

Can set duration and volume with arguments. This example makes 2 seconds, 50% volume.

>>> sound = Sound.from_sinwave(440, duration=2.0, volume=0.5)

Can make 2 seconds sine wave with repeat too. But, this way may make noise at the joint point of sounds. Recommend using from_sinwave() as possible.

Make a smooth end if smooth_end is true. but duration will inaccuracy. This error is not critical most cases so smooth_end is true by default.

>>> sound = Sound.from_sinwave(880, duration=1.0, smooth_end=True)
>>> sound.duration
1.017687074829932

Please pass false to smooth_end if want accurate duration. But please be careful, may make noise in end of sound if disable smooth_end.

>>> sound = Sound.from_sinwave(880, duration=1.0, smooth_end=False)
>>> sound.duration
1.0

classmethod from_sawtoothwave(frequency, duration=1.0, volume=1.0, samplerate=44100)

Generate sawtooth wave sound

Parameters:

• frequency (float) – Frequency of new sound.
• duration (float) – Duration in seconds of new sound.
• volume (float) – The volume of new sound.
• samplerate (float) – Sampling rate of new sound.

Return type:

Sound

Returns:

A new Sound instance.

Raises:

• InvalidDurationError – Duration was 0 or less.
• InvalidFrequencyError – Frequency was 0 or less.
• InvalidSamplerateError – Samplerate was 0 or less.
• InvalidVolumeError – Volume was lower than 0.0 or higher than 1.0.

classmethod from_squarewave(frequency, duration=1.0, volume=1.0, samplerate=44100)

Generate square wave sound

Parameters:

• frequency (float) – Frequency of new sound.
• duration (float) – Duration in seconds of new sound.
• volume (float) – The volume of new sound.
• samplerate (float) – Sampling rate of new sound.

Return type:

Sound

Returns:

A new Sound instance.

Raises:

• InvalidDurationError – Duration was 0 or less.
• InvalidFrequencyError – Frequency was 0 or less.
• InvalidSamplerateError – Samplerate was 0 or less.
• InvalidVolumeError – Volume was lower than 0.0 or higher than 1.0.

classmethod silence(duration=1.0, samplerate=44100)

Generate silent sound

Duration:

Duration of new sound.

Samplerate:

Sampling rate of new sound.

Return type:

Sound

Returns:

A new Sound instance.

Raises:

• InvalidDurationError – Duration was 0 or less.
• InvalidSamplerateError – Samplerate was 0 or less.

classmethod from_whitenoise(duration=1.0, volume=1.0, samplerate=44100)

Generate white noise

Parameters:

• duration (float) – Duration in seconds of new sound.
• volume (float) – The volume of new sound.
• samplerate (float) – Sampling rate of new sound.

Return type:

Sound

Returns:

A new Sound instance.

Raises:

• InvalidDurationError – Duration was 0 or less.
• InvalidSamplerateError – Samplerate was 0 or less.
• InvalidVolumeError – Volume was lower than 0.0 or higher than 1.0.

classmethod from_file(file_)

Read sound from file or file-like

Parameters:file (Union[str, BinaryIO]) – File name or file-like object. Return type:Sound Returns:A new Sound instance.

classmethod from_array(array, samplerate)

Make new sound from float array

Parameters:

• array (Sequence[float]) – Sound data. Elements must in between -1.0 to 1.0.
• samplerate (float) – Sampling rate of new sound.

Return type:

Sound

Returns:

A new Sound instance.

Raises:

• InvalidDurationError – The array was empty.
• InvalidSamplerateError – Samplerate was 0 or less.

This method is same as passing numpy.array to the Sound constructor.

>>> (Sound.from_array([-0.1, 0.0, 1.0], 3)
...  == Sound(numpy.array([-0.1, 0.0, 1.0]), 3))
True

classmethod from_fft(spectrum, samplerate=None)

Make new sound from spectrum data like a result from fft() method.

Parameters:

• spectrum (<built-in function array>) – A spectrum data. Please see fft() method about a format.
• samplerate (Optional[float]) – Sampling rate of new sound. Use spectrum data if None.

Return type:

Sound

Returns:

A new Sound instance.

Raises:

• InvalidDurationError – Duration was 0 or less.
• InvalidSamplerateError – Samplerate was 0 or less.

duration

Duration in seconds of this sound

Return type:float

samplerate

Sampling rate of this sound

Return type:float

n_channels

Number of channels

Return type:int

volume

Volume of this dound

This volume means the maximum value of the wave. Please be careful that is not gain.

Return type:float

data

Raw data of sound

This array is two dimensions. The first dimension means time, and the second dimension means channels.

Return type:<built-in function array>

split_channels()

Split channels into Sound

Return type:Sequence[<built-in function array>] Returns:A list of Sound instances.

as_monaural()

Create a new instance that converted to monaural sound

Return type:Sound Returns:A Sound instance that monaural.

If an instance already monaural sound, may returns the same instance.

as_stereo(channels=2)

Create a new instance that converted to multi channel sound

Return type:Sound Returns:A new Sound instance that stereo or multi channel. Raises:ValueError – A given channels were lesser than a number of channels of this sound.

This method will return the same instance if this sound already had the same number of channels.

fft()

Calculate fft

Return type:<built-in function array> Returns:An array that pair of frequency and value.

repeat(duration)

Create a new instance that repeated same sound

Parameters:duration (float) – Duration in seconds to repeat. Return type:Sound Returns:A new Sound instance that repeated same sound. Raises:InvalidDurationError – Duration was shorter than 0.

>>> sound = Sound.from_sinwave(440)
>>> sound.repeat(5).duration
5.0

This function can not only repeat but trimming. But recommend use slice because become hard to understand if using it for trimming.

>>> sound.repeat(0.5).duration
0.5
>>> sound.repeat(0.5) == sound[:0.5]
True

concat(another)

Create a new instance that concatenated another sound

Parameters:

another (Sound) – The sound that concatenates after of self. Must it has same sampling rate.

Return type:

Sound

Returns:

A new Sound that concatenated self and other.

Raises:

• DifferentSamplerateError – The samplerate was different.
• DifferentChannelsError – The number of channels was different.

>>> sound = Sound.from_sinwave(440, duration=3)
>>> a, b = sound[:1], sound[1:]
>>> a.concat(b) == sound
True

Recommend using concat function instead of this method if concatenate many sounds. Because concat function is optimized for many sounds.

>>> concat(a, b) == a.concat(b)
True

overlay(another)

Create a new instance that was overlay another sound

Parameters:

another (Sound) – The sound that overlay.

Return type:

Sound

Returns:

A new Sound that overlay another sound.

Raises:

• DifferentSamplerateError – The samplerate was different.
• DifferentChannelsError – The number of channels was different.

>>> a = Sound.from_array([0.1, 0.2], 1)
>>> b = Sound.from_array([0.1, 0.2, 0.3], 1)
>>> a.overlay(b) == Sound.from_array([0.2, 0.4, 0.3], 1)
True

Recommend using overlay function instead of this method if overlay many sounds. Because overlay function is optimized for many sounds.

>>> overlay(a, b) == a.overlay(b)
True

write(file_, format_=None)

Write sound into file or file-like

Parameters:

• file (Union[str, BinaryIO]) – A file name or file-like object to write sound.
• format (Optional[str]) – Format type of output like a ‘wav’. Automatically detect from file name if None.

Return type:

None

play()

Play sound

Return type:None

gensound.sound.concat(*sounds)

Concatenate multiple sounds

Parameters:

sounds (Sound) – Sound instances to concatenate. Must they has some sampling rate.

Return type:

Sound

Returns:

A concatenated Sound instance.

Raises:

• DifferentSamplerateError – The samplerate of sounds was different.
• DifferentChannelsError – The number of channels of sounds was different.

>>> a = Sound.from_array([0.1, 0.2], 1)
>>> b = Sound.from_array([0.3, 0.4], 1)
>>> c = Sound.from_array([0.5, 0.6], 1)
>>> concat(a, b, c) == Sound.from_array([0.1, 0.2, 0.3, 0.4, 0.5, 0.6], 1)
True

gensound.sound.overlay(*sounds)

Overlay multiple sounds

Parameters:

sounds (Sound) – Sound instances to overlay. Must they has some sampling rate.

Return type:

Sound

Returns:

A new Sound instance that overlay all sounds.

Raises:

• DifferentSamplerateError – The samplerate of sounds was different.
• DifferentChannelsError – The number of channels of sounds was different.

BE CAREFUL: This function doesn’t care about clipping. Perhaps, need to

change volume before use this if overlay many sounds.

>>> a = Sound.from_array([0.1, 0.2], 1)
>>> b = Sound.from_array([0.3, 0.4], 1)
>>> c = Sound.from_array([0.5, 0.6], 1)
>>> overlay(a, b, c) == Sound.from_array([0.9, 1.0], 1)
True

The second element of this sample isn’t 1.2 but 1.0 because of clipping was an occurrence.

gensound.sound.merge_channels(*sounds)

Merge multiple sounds as a sound that has multiple channels

Parameters:sounds (Sound) – Sound instances to merge. Must they has some sampling rate. Return type:Sound Returns:A new Sound that merged sounds as channels. Raises:DifferentSamplerateError – The samplerate of sounds was different.

BE CAREFUL: all sounds calculate as monaural sound.