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
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:
%% Cell type:code id: tags:
``` python
w_left=w_stereo[:,0]
w_right=w_stereo[:,1]
w_left.plot(label='left mono')
w_right.plot(label='right mono')
legend()
print('Is w_left stereo?',w_left.is_stereo())
print('Is w_right stereo?',w_left.is_stereo())
print(w_left)
print(w_right)
```
%% Cell type:markdown id: tags:
## Special audio abilities
### Resampling
A *Waveform* can be resampled by setting a new value to the attribute *fs*
%% Cell type:code id: tags:
``` python
wr=Waveform(w)
wr.resample(22050)
plt.subplot(211)
w.plot()
plt.subplot(212)
wr.plot()
print(w)
print(wr)
```
%% Cell type:markdown id: tags:
### Changing the sampling frequency without resampling the waveform
%% Cell type:code id: tags:
``` python
w_fs=Waveform(w)
w_fs.fs=22050
plt.subplot(211)
w.plot()
plt.subplot(212)
w_fs.plot()
print(w)
print(w_fs)
```
%% Cell type:markdown id: tags:
### 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.
%% Cell type:code id: tags:
``` python
w_rms=Waveform(w)
plt.subplot(211)
w_rms.plot()
print('RMS before modification: ',w_rms.rms)
w_rms.set_rms(1)
plt.subplot(212)
w_rms.plot()
print('RMS after modification: ',w_rms.rms)
```
%% Cell type:markdown id: tags:
### Properties
A *Waveform* has several attributes that give information about the audio signal
%% Cell type:code id: tags:
``` python
print('Length: {} samples'.format(w.length))
print('Duration: {} s'.format(w.duration))
print('Time axis: {}'.format(w.time_axis))
```
%% Cell type:markdown id: tags:
### Plotting
A *Waveform* can be plotted, as well as the associated mask.
%% Cell type:code id: tags:
``` python
plt.figure()
wm.plot()
plt.title('Audio signal')
plt.figure()
wm.plot_mask()
plt.title('Mask')
pass
```
%% Cell type:markdown id: tags:
### Playing sound
The sound can be played using *show_player* in a notebook or *play* in a console.
%% Cell type:code id: tags:
``` python
w.show_player()
```
%% Cell type:markdown id: tags:
#### I/O
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
**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.
%% Cell type:markdown id: tags:
### Clipping
Two approaches are implemented to clip a *Waveform*:
* using minimal and maximal values; this is the regular way to clip signals;
* for int-valued waveform, using the bounds of a given int type; this is mainly used by method *astype* for conversion purposes.
%% Cell type:code id: tags:
``` python
wm_clipped=wm.copy()
wm_clipped.clip(min_value=-0.75,max_value=0.25)
# Plot signals
plt.figure()
wm.plot('b',label='x')
wm_clipped.plot('y',label='y')
plt.legend()
```
%% Cell type:code id: tags:
``` python
# Generate a random sine wave
t=np.linspace(0,10,10000)
x=(2**16*np.cos(2*np.pi*t)).astype(np.int32)
w_int=Waveform(x,fs=1)
w_clipped=Waveform(x,fs=1)
# Clip the signal
w_clipped.astype(np.int16)
# Plot signals
plt.figure()
w_int.plot('b',label='x')
w_clipped.plot('y',label='y')
plt.legend()
```
%% Cell type:markdown id: tags:
## Type of entries in Waveform
This section is for advanced usages.
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;
**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.
%% Cell type:markdown id: tags:
### Integer-valued waveforms
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:
**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-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.
These constraints are only applied when calling explicitely the method `astype`.
Clipping is performed for unexpected values:
* 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:
* $\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.
