"* sampling frequency: only a restricted set of sampling frequencies are allowed for input/output (see set of supported frequencies `waveform.VALID_IO_FS`)\n",
"* *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*.\n",
"* mask: the mask is lost when exporting to a .wav file.\n"
"* mask: the mask is lost when exporting to a .wav file.\n",
"* sampling frequency: sampling frequencies may be arbitrary ``float`` or ``int`` values; however, only a restricted set of sampling frequencies are allowed for input/output (see set of supported frequencies ``madarrays.waveform.VALID_IO_FS` below).\n"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"from madarrays.waveform import VALID_IO_FS\n",
"print(VALID_IO_FS)"
]
},
{
...
...
%% Cell type:code id: tags:
``` python
%pylabinline
```
%% Cell type:markdown id: tags:
# Tutorial on how to use `Waveform` objects
%% Cell type:markdown id: tags:
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 using the *resample* method:
%% 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 (see set of supported frequencies `waveform.VALID_IO_FS`)
**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.
* sampling frequency: sampling frequencies may be arbitrary ``float`` or ``int`` values; however, only a restricted set of sampling frequencies are allowed for input/output (see set of supported frequencies ``madarrays.waveform.VALID_IO_FS` below).
%% Cell type:code id: tags:
``` python
from madarrays.waveform import VALID_IO_FS
print(VALID_IO_FS)
```
%% Cell type:markdown id: tags:
### 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.
%% 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: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 choice among the available integer types will result in different ranges. The following figures show integer-valued waveforms with different types: on the first row, waveforms created without conversion, from integer-valued data arrays where the full `dtype` range is used; on the second row, similar waveforms are created with a conversion from a float-valued array with entries in [-1, 1].
The choice among the available float types will not affect the range of the values but the precision. In the following example, one may observe how the floating-point precision varies, depending on the float type, when the fractionnal part is very small compared to the exponent part, which equals 1 here (see right column).
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.
