A *Waveform* is a *MadArray* dedicated to handle audio signals. As such, it has a mandatory attribute *fs*, giving the sampling frequency of the signal.
A *Waveform* is a *MadArray* dedicated to handle audio signals. As such, it has a mandatory attribute *fs*, giving the sampling frequency of the signal.
## Initialization
## Initialization
As for *MadArray*, *Waveform* can be initialized from a 1D nd-array with or without mask. The parameter *fs* should be explicitly given.
As for *MadArray*, *Waveform* can be initialized from a 1D nd-array with or without mask. The parameter *fs* should be explicitly given.
Extracting left and right channels as mono *Waveform* objects is easy:
Extracting left and right channels as mono *Waveform* objects is easy:
%% Cell type:code id: tags:
%% Cell type:code id: tags:
``` python
``` python
w_left=w_stereo[:,0]
w_left=w_stereo[:,0]
w_right=w_stereo[:,1]
w_right=w_stereo[:,1]
w_left.plot(label='left mono')
w_left.plot(label='left mono')
w_right.plot(label='right mono')
w_right.plot(label='right mono')
legend()
legend()
print('Is w_left stereo?',w_left.is_stereo())
print('Is w_left stereo?',w_left.is_stereo())
print('Is w_right stereo?',w_left.is_stereo())
print('Is w_right stereo?',w_left.is_stereo())
print(w_left)
print(w_left)
print(w_right)
print(w_right)
```
```
%% Cell type:markdown id: tags:
%% Cell type:markdown id: tags:
## Special audio abilities
## Special audio abilities
### Resampling
### Resampling
A *Waveform* can be resampled using the *resample* method:
A *Waveform* can be resampled using the *resample* method:
%% Cell type:code id: tags:
%% Cell type:code id: tags:
``` python
``` python
wr=Waveform(w)
wr=Waveform(w)
wr.resample(22050)
wr.resample(22050)
plt.subplot(211)
plt.subplot(211)
w.plot()
w.plot()
plt.subplot(212)
plt.subplot(212)
wr.plot()
wr.plot()
print(w)
print(w)
print(wr)
print(wr)
```
```
%% Cell type:markdown id: tags:
%% Cell type:markdown id: tags:
### Changing the sampling frequency without resampling the waveform
### Changing the sampling frequency without resampling the waveform
%% Cell type:code id: tags:
%% Cell type:code id: tags:
``` python
``` python
w_fs=Waveform(w)
w_fs=Waveform(w)
w_fs.fs=22050
w_fs.fs=22050
plt.subplot(211)
plt.subplot(211)
w.plot()
w.plot()
plt.subplot(212)
plt.subplot(212)
w_fs.plot()
w_fs.plot()
print(w)
print(w)
print(w_fs)
print(w_fs)
```
```
%% Cell type:markdown id: tags:
%% Cell type:markdown id: tags:
### Intensity
### Intensity
A *Waveform* has an attribute *rms* giving the root mean square of the audio signal (where missing samples equal zero). It can be changed by setting a new value.
A *Waveform* has an attribute *rms* giving the root mean square of the audio signal (where missing samples equal zero). It can be changed by setting a new value.
%% Cell type:code id: tags:
%% Cell type:code id: tags:
``` python
``` python
w_rms=Waveform(w)
w_rms=Waveform(w)
plt.subplot(211)
plt.subplot(211)
w_rms.plot()
w_rms.plot()
print('RMS before modification: ',w_rms.rms)
print('RMS before modification: ',w_rms.rms)
w_rms.set_rms(1)
w_rms.set_rms(1)
plt.subplot(212)
plt.subplot(212)
w_rms.plot()
w_rms.plot()
print('RMS after modification: ',w_rms.rms)
print('RMS after modification: ',w_rms.rms)
```
```
%% Cell type:markdown id: tags:
%% Cell type:markdown id: tags:
### Properties
### Properties
A *Waveform* has several attributes that give information about the audio signal
A *Waveform* has several attributes that give information about the audio signal
%% Cell type:code id: tags:
%% Cell type:code id: tags:
``` python
``` python
print('Length: {} samples'.format(w.length))
print('Length: {} samples'.format(w.length))
print('Duration: {} s'.format(w.duration))
print('Duration: {} s'.format(w.duration))
print('Time axis: {}'.format(w.time_axis))
print('Time axis: {}'.format(w.time_axis))
```
```
%% Cell type:markdown id: tags:
%% Cell type:markdown id: tags:
### Plotting
### Plotting
A *Waveform* can be plotted, as well as the associated mask.
A *Waveform* can be plotted, as well as the associated mask.
%% Cell type:code id: tags:
%% Cell type:code id: tags:
``` python
``` python
plt.figure()
plt.figure()
wm.plot()
wm.plot()
plt.title('Audio signal')
plt.title('Audio signal')
plt.figure()
plt.figure()
wm.plot_mask()
wm.plot_mask()
plt.title('Mask')
plt.title('Mask')
pass
pass
```
```
%% Cell type:markdown id: tags:
%% Cell type:markdown id: tags:
### Playing sound
### Playing sound
The sound can be played using *show_player* in a notebook or *play* in a console.
The sound can be played using *show_player* in a notebook or *play* in a console.
%% Cell type:code id: tags:
%% Cell type:code id: tags:
``` python
``` python
w.show_player()
w.show_player()
```
```
%% Cell type:markdown id: tags:
%% Cell type:markdown id: tags:
#### I/O
#### I/O
A *Waveform* can be exported as a .wav file using *to_wavfile*:
A *Waveform* can be exported as a .wav file using *to_wavfile*:
* sampling frequency: only a restricted set of sampling frequencies are allowed for input/output
* sampling frequency: only a restricted set of sampling frequencies are allowed for input/output
**dtype*: float/int data types are conserved when exporting a *Waveform*, since the .wav format allows many data types. However, many audio players only read .wav files coded with int16 values so you may not be able to listen to your exported sound with your favorite player. In that case, you may convert the data type of your *Waveform* using the optional *dtype* argument of method *to_wavfile*.
**dtype*: float/int data types are conserved when exporting a *Waveform*, since the .wav format allows many data types. However, many audio players only read .wav files coded with int16 values so you may not be able to listen to your exported sound with your favorite player. In that case, you may convert the data type of your *Waveform* using the optional *dtype* argument of method *to_wavfile*.
* mask: the mask is lost when exporting to a .wav file.
* mask: the mask is lost when exporting to a .wav file.
%% Cell type:markdown id: tags:
%% Cell type:markdown id: tags:
### Clipping
### Clipping
Clipping a *Waveform* is done by using the `clip` method, taking as arguments the minimal and maximal values. Warnings are displayed to inform the user if any value has been clipped.
Clipping a *Waveform* is done by using the `clip` method, taking as arguments the minimal and maximal values. Warnings are displayed to inform the user if any value has been clipped.
%% Cell type:code id: tags:
%% Cell type:code id: tags:
``` python
``` python
wm_clipped=wm.copy()
wm_clipped=wm.copy()
wm_clipped.clip(min_value=-0.75,max_value=0.25)
wm_clipped.clip(min_value=-0.75,max_value=0.25)
# Plot signals
# Plot signals
plt.figure()
plt.figure()
wm.plot('b',label='x')
wm.plot('b',label='x')
wm_clipped.plot('y',label='y')
wm_clipped.plot('y',label='y')
plt.legend()
plt.legend()
```
```
%% Cell type:markdown id: tags:
%% Cell type:markdown id: tags:
## Type of entries in Waveform
## Type of entries in Waveform
This section is for advanced usages.
This section is for advanced usages.
Audio data can have different types, that are associated with specific constraints on the values:
Audio data can have different types, that are associated with specific constraints on the values:
**float* (np.float16, no.float32, np.float64): the values are float between -1 and 1;
**float* (np.float16, no.float32, np.float64): the values are float between -1 and 1;
**int* (np.uint8, np.int16, np.int32): the values are integers between a range that depends on the precision.
**int* (np.uint8, np.int16, np.int32): the values are integers between a range that depends on the precision.
**complex* (np.complex64, np.complex128): the real and imaginary parts are float betwen -1 and 1.
**complex* (np.complex64, np.complex128): the real and imaginary parts are float betwen -1 and 1.
%% Cell type:markdown id: tags:
%% Cell type:markdown id: tags:
### Integer-valued waveforms
### Integer-valued waveforms
Method *Waveform.astype* not only converts data types but also scale values to the range of the target type.
Method *Waveform.astype* not only converts data types but also scale values to the range of the target type.
The casting of a waveform in a different dtype depends on the current dtype and the desired dtype:
The casting of a waveform in a different dtype depends on the current dtype and the desired dtype:
**Integer-to-real* casting is performed by applying on each entry $x$ the function $f(x)=\frac{x - z}{2^{n-1}}$, where the source integral type is coded with $n$ bits, and $z$ is the integer associated with zero, i.e., $z=0$ for a signed type (`int`) and $z=2^{n-1}$ for an unsigned type (`uint`).
**Integer-to-real* casting is performed by applying on each entry $x$ the function $f(x)=\frac{x - z}{2^{n-1}}$, where the source integral type is coded with $n$ bits, and $z$ is the integer associated with zero, i.e., $z=0$ for a signed type (`int`) and $z=2^{n-1}$ for an unsigned type (`uint`).
**Real-to-integer* casting is performed by applying on each entry $x$ the function $f(x)=\lfloor\left(x + 1\right) 2^{n-1} + m\rfloor$, where the target integral type is coded with $n$ bits, and $m$ is the minimum integer value, i.e., $m=-2^{n-1}$ for a signed type (`int`) and $z=0$ for an unsigned type (`uint`);
**Real-to-integer* casting is performed by applying on each entry $x$ the function $f(x)=\lfloor\left(x + 1\right) 2^{n-1} + m\rfloor$, where the target integral type is coded with $n$ bits, and $m$ is the minimum integer value, i.e., $m=-2^{n-1}$ for a signed type (`int`) and $z=0$ for an unsigned type (`uint`);
**Real-to-real* casting is obtained by a basic rounding operation;
**Real-to-real* casting is obtained by a basic rounding operation;
**Integer-to-integer* casting is obtained by chaining an integer-to-float64 casting and a float64-to-integer casting.
**Integer-to-integer* casting is obtained by chaining an integer-to-float64 casting and a float64-to-integer casting.
These constraints are only applied when calling explicitely the method `astype`.
These constraints are only applied when calling explicitely the method `astype`.
Clipping is performed for unexpected values:
Clipping is performed for unexpected values:
* When casting to `float`, values outside $[-1, 1]$ are clipped;
* When casting to `float`, values outside $[-1, 1]$ are clipped;
* When casting to `int`, values outside the minimum and maximum values allowed by the integral type are clipped:
* When casting to `int`, values outside the minimum and maximum values allowed by the integral type are clipped:
* $\left[-2^{n-1}, 2^{n-1}-1\right]$ for $n$-bits signed integers;
* $\left[-2^{n-1}, 2^{n-1}-1\right]$ for $n$-bits signed integers;
* $\left[0, 2^{n}-1\right]$ for $n$-bits unsigned integers.
* $\left[0, 2^{n}-1\right]$ for $n$-bits unsigned integers.
