mirror of https://github.com/morpheus65535/bazarr
1459 lines
52 KiB
Python
1459 lines
52 KiB
Python
"""
|
|
.. autosummary::
|
|
:toctree: generated/
|
|
|
|
load
|
|
split
|
|
AudioRegion
|
|
StreamTokenizer
|
|
"""
|
|
import os
|
|
import math
|
|
from .util import AudioReader, DataValidator, AudioEnergyValidator
|
|
from .io import check_audio_data, to_file, player_for, get_audio_source
|
|
from .exceptions import TooSamllBlockDuration
|
|
|
|
try:
|
|
from . import signal_numpy as signal
|
|
except ImportError:
|
|
from . import signal
|
|
|
|
__all__ = ["load", "split", "AudioRegion", "StreamTokenizer"]
|
|
|
|
|
|
DEFAULT_ANALYSIS_WINDOW = 0.05
|
|
DEFAULT_ENERGY_THRESHOLD = 50
|
|
_EPSILON = 1e-10
|
|
|
|
|
|
def load(input, skip=0, max_read=None, **kwargs):
|
|
"""Load audio data from a source and return it as an :class:`AudioRegion`.
|
|
|
|
Parameters
|
|
----------
|
|
input : None, str, bytes, AudioSource
|
|
source to read audio data from. If `str`, it should be a path to a
|
|
valid audio file. If `bytes`, it is used as raw audio data. If it is
|
|
"-", raw data will be read from stdin. If None, read audio data from
|
|
the microphone using PyAudio. If of type `bytes` or is a path to a
|
|
raw audio file then `sampling_rate`, `sample_width` and `channels`
|
|
parameters (or their alias) are required. If it's an
|
|
:class:`AudioSource` object it's used directly to read data.
|
|
skip : float, default: 0
|
|
amount, in seconds, of audio data to skip from source. If read from
|
|
a microphone, `skip` must be 0, otherwise a `ValueError` is raised.
|
|
max_read : float, default: None
|
|
amount, in seconds, of audio data to read from source. If read from
|
|
microphone, `max_read` should not be None, otherwise a `ValueError` is
|
|
raised.
|
|
audio_format, fmt : str
|
|
type of audio data (e.g., wav, ogg, flac, raw, etc.). This will only
|
|
be used if `input` is a string path to an audio file. If not given,
|
|
audio type will be guessed from file name extension or from file
|
|
header.
|
|
sampling_rate, sr : int
|
|
sampling rate of audio data. Required if `input` is a raw audio file,
|
|
a `bytes` object or None (i.e., read from microphone).
|
|
sample_width, sw : int
|
|
number of bytes used to encode one audio sample, typically 1, 2 or 4.
|
|
Required for raw data, see `sampling_rate`.
|
|
channels, ch : int
|
|
number of channels of audio data. Required for raw data, see
|
|
`sampling_rate`.
|
|
large_file : bool, default: False
|
|
If True, AND if `input` is a path to a *wav* of a *raw* audio file
|
|
(and **only** these two formats) then audio file is not fully loaded to
|
|
memory in order to create the region (but the portion of data needed to
|
|
create the region is of course loaded to memory). Set to True if
|
|
`max_read` is significantly smaller then the size of a large audio file
|
|
that shouldn't be entirely loaded to memory.
|
|
|
|
Returns
|
|
-------
|
|
region: AudioRegion
|
|
|
|
Raises
|
|
------
|
|
ValueError
|
|
raised if `input` is None (i.e., read data from microphone) and `skip`
|
|
!= 0 or `input` is None `max_read` is None (meaning that when reading
|
|
from the microphone, no data should be skipped, and maximum amount of
|
|
data to read should be explicitly provided).
|
|
"""
|
|
return AudioRegion.load(input, skip, max_read, **kwargs)
|
|
|
|
|
|
def split(
|
|
input,
|
|
min_dur=0.2,
|
|
max_dur=5,
|
|
max_silence=0.3,
|
|
drop_trailing_silence=False,
|
|
strict_min_dur=False,
|
|
**kwargs
|
|
):
|
|
"""
|
|
Split audio data and return a generator of AudioRegions
|
|
|
|
Parameters
|
|
----------
|
|
input : str, bytes, AudioSource, AudioReader, AudioRegion or None
|
|
input audio data. If str, it should be a path to an existing audio file.
|
|
"-" is interpreted as standard input. If bytes, input is considered as
|
|
raw audio data. If None, read audio from microphone.
|
|
Every object that is not an `AudioReader` will be transformed into an
|
|
`AudioReader` before processing. If it is an `str` that refers to a raw
|
|
audio file, `bytes` or None, audio parameters should be provided using
|
|
kwargs (i.e., `samplig_rate`, `sample_width` and `channels` or their
|
|
alias).
|
|
If `input` is str then audio format will be guessed from file extension.
|
|
`audio_format` (alias `fmt`) kwarg can also be given to specify audio
|
|
format explicitly. If none of these options is available, rely on
|
|
backend (currently only pydub is supported) to load data.
|
|
min_dur : float, default: 0.2
|
|
minimun duration in seconds of a detected audio event. By using large
|
|
values for `min_dur`, very short audio events (e.g., very short 1-word
|
|
utterances like 'yes' or 'no') can be mis detected. Using very short
|
|
values might result in a high number of short, unuseful audio events.
|
|
max_dur : float, default: 5
|
|
maximum duration in seconds of a detected audio event. If an audio event
|
|
lasts more than `max_dur` it will be truncated. If the continuation of a
|
|
truncated audio event is shorter than `min_dur` then this continuation
|
|
is accepted as a valid audio event if `strict_min_dur` is False.
|
|
Otherwise it is rejected.
|
|
max_silence : float, default: 0.3
|
|
maximum duration of continuous silence within an audio event. There
|
|
might be many silent gaps of this duration within one audio event. If
|
|
the continuous silence happens at the end of the event than it's kept as
|
|
part of the event if `drop_trailing_silence` is False (default).
|
|
drop_trailing_silence : bool, default: False
|
|
Whether to remove trailing silence from detected events. To avoid abrupt
|
|
cuts in speech, trailing silence should be kept, therefore this
|
|
parameter should be False.
|
|
strict_min_dur : bool, default: False
|
|
strict minimum duration. Do not accept an audio event if it is shorter
|
|
than `min_dur` even if it is contiguous to the latest valid event. This
|
|
happens if the the latest detected event had reached `max_dur`.
|
|
|
|
Other Parameters
|
|
----------------
|
|
analysis_window, aw : float, default: 0.05 (50 ms)
|
|
duration of analysis window in seconds. A value between 0.01 (10 ms) and
|
|
0.1 (100 ms) should be good for most use-cases.
|
|
audio_format, fmt : str
|
|
type of audio data (e.g., wav, ogg, flac, raw, etc.). This will only be
|
|
used if `input` is a string path to an audio file. If not given, audio
|
|
type will be guessed from file name extension or from file header.
|
|
sampling_rate, sr : int
|
|
sampling rate of audio data. Required if `input` is a raw audio file, is
|
|
a bytes object or None (i.e., read from microphone).
|
|
sample_width, sw : int
|
|
number of bytes used to encode one audio sample, typically 1, 2 or 4.
|
|
Required for raw data, see `sampling_rate`.
|
|
channels, ch : int
|
|
number of channels of audio data. Required for raw data, see
|
|
`sampling_rate`.
|
|
use_channel, uc : {None, "mix"} or int
|
|
which channel to use for split if `input` has multiple audio channels.
|
|
Regardless of which channel is used for splitting, returned audio events
|
|
contain data from *all* channels, just as `input`.
|
|
The following values are accepted:
|
|
|
|
- None (alias "any"): accept audio activity from any channel, even if
|
|
other channels are silent. This is the default behavior.
|
|
|
|
- "mix" ("avg" or "average"): mix down all channels (i.e. compute
|
|
average channel) and split the resulting channel.
|
|
|
|
- int (0 <=, > `channels`): use one channel, specified by integer id,
|
|
for split.
|
|
|
|
large_file : bool, default: False
|
|
If True, AND if `input` is a path to a *wav* of a *raw* audio file
|
|
(and only these two formats) then audio data is lazily loaded to memory
|
|
(i.e., one analysis window a time). Otherwise the whole file is loaded
|
|
to memory before split. Set to True if the size of the file is larger
|
|
than available memory.
|
|
max_read, mr : float, default: None, read until end of stream
|
|
maximum data to read from source in seconds.
|
|
validator, val : callable, DataValidator
|
|
custom data validator. If `None` (default), an `AudioEnergyValidor` is
|
|
used with the given energy threshold. Can be a callable or an instance
|
|
of `DataValidator` that implements `is_valid`. In either case, it'll be
|
|
called with with a window of audio data as the first parameter.
|
|
energy_threshold, eth : float, default: 50
|
|
energy threshold for audio activity detection. Audio regions that have
|
|
enough windows of with a signal energy equal to or above this threshold
|
|
are considered valid audio events. Here we are referring to this amount
|
|
as the energy of the signal but to be more accurate, it is the log
|
|
energy of computed as: `20 * log10(sqrt(dot(x, x) / len(x)))` (see
|
|
:class:`AudioEnergyValidator` and
|
|
:func:`calculate_energy_single_channel`). If `validator` is given, this
|
|
argument is ignored.
|
|
|
|
Yields
|
|
------
|
|
AudioRegion
|
|
a generator of detected :class:`AudioRegion` s.
|
|
"""
|
|
if min_dur <= 0:
|
|
raise ValueError("'min_dur' ({}) must be > 0".format(min_dur))
|
|
if max_dur <= 0:
|
|
raise ValueError("'max_dur' ({}) must be > 0".format(max_dur))
|
|
if max_silence < 0:
|
|
raise ValueError("'max_silence' ({}) must be >= 0".format(max_silence))
|
|
|
|
if isinstance(input, AudioReader):
|
|
source = input
|
|
analysis_window = source.block_dur
|
|
else:
|
|
analysis_window = kwargs.get(
|
|
"analysis_window", kwargs.get("aw", DEFAULT_ANALYSIS_WINDOW)
|
|
)
|
|
if analysis_window <= 0:
|
|
raise ValueError(
|
|
"'analysis_window' ({}) must be > 0".format(analysis_window)
|
|
)
|
|
|
|
params = kwargs.copy()
|
|
params["max_read"] = params.get("max_read", params.get("mr"))
|
|
params["audio_format"] = params.get("audio_format", params.get("fmt"))
|
|
if isinstance(input, AudioRegion):
|
|
params["sampling_rate"] = input.sr
|
|
params["sample_width"] = input.sw
|
|
params["channels"] = input.ch
|
|
input = bytes(input)
|
|
try:
|
|
source = AudioReader(input, block_dur=analysis_window, **params)
|
|
except TooSamllBlockDuration as exc:
|
|
err_msg = "Too small 'analysis_windows' ({0}) for sampling rate "
|
|
err_msg += "({1}). Analysis windows should at least be 1/{1} to "
|
|
err_msg += "cover one single data sample"
|
|
raise ValueError(err_msg.format(exc.block_dur, exc.sampling_rate))
|
|
|
|
validator = kwargs.get("validator", kwargs.get("val"))
|
|
if validator is None:
|
|
energy_threshold = kwargs.get(
|
|
"energy_threshold", kwargs.get("eth", DEFAULT_ENERGY_THRESHOLD)
|
|
)
|
|
use_channel = kwargs.get("use_channel", kwargs.get("uc"))
|
|
validator = AudioEnergyValidator(
|
|
energy_threshold, source.sw, source.ch, use_channel=use_channel
|
|
)
|
|
mode = StreamTokenizer.DROP_TRAILING_SILENCE if drop_trailing_silence else 0
|
|
if strict_min_dur:
|
|
mode |= StreamTokenizer.STRICT_MIN_LENGTH
|
|
min_length = _duration_to_nb_windows(min_dur, analysis_window, math.ceil)
|
|
max_length = _duration_to_nb_windows(
|
|
max_dur, analysis_window, math.floor, _EPSILON
|
|
)
|
|
max_continuous_silence = _duration_to_nb_windows(
|
|
max_silence, analysis_window, math.floor, _EPSILON
|
|
)
|
|
|
|
err_msg = "({0} sec.) results in {1} analysis window(s) "
|
|
err_msg += "({1} == {6}({0} / {2})) which is {5} the number "
|
|
err_msg += "of analysis window(s) for 'max_dur' ({3} == floor({4} / {2}))"
|
|
if min_length > max_length:
|
|
err_msg = "'min_dur' " + err_msg
|
|
raise ValueError(
|
|
err_msg.format(
|
|
min_dur,
|
|
min_length,
|
|
analysis_window,
|
|
max_length,
|
|
max_dur,
|
|
"higher than",
|
|
"ceil",
|
|
)
|
|
)
|
|
|
|
if max_continuous_silence >= max_length:
|
|
err_msg = "'max_silence' " + err_msg
|
|
raise ValueError(
|
|
err_msg.format(
|
|
max_silence,
|
|
max_continuous_silence,
|
|
analysis_window,
|
|
max_length,
|
|
max_dur,
|
|
"higher or equal to",
|
|
"floor",
|
|
)
|
|
)
|
|
|
|
tokenizer = StreamTokenizer(
|
|
validator, min_length, max_length, max_continuous_silence, mode=mode
|
|
)
|
|
source.open()
|
|
token_gen = tokenizer.tokenize(source, generator=True)
|
|
region_gen = (
|
|
_make_audio_region(
|
|
token[0],
|
|
token[1],
|
|
source.block_dur,
|
|
source.sr,
|
|
source.sw,
|
|
source.ch,
|
|
)
|
|
for token in token_gen
|
|
)
|
|
return region_gen
|
|
|
|
|
|
def _duration_to_nb_windows(
|
|
duration, analysis_window, round_fn=round, epsilon=0
|
|
):
|
|
"""
|
|
Converts a given duration into a positive integer of analysis windows.
|
|
if `duration / analysis_window` is not an integer, the result will be
|
|
rounded to the closest bigger integer. If `duration == 0`, returns `0`.
|
|
If `duration < analysis_window`, returns 1.
|
|
`duration` and `analysis_window` can be in seconds or milliseconds but
|
|
must be in the same unit.
|
|
|
|
Parameters
|
|
----------
|
|
duration : float
|
|
a given duration in seconds or ms.
|
|
analysis_window: float
|
|
size of analysis window, in the same unit as `duration`.
|
|
round_fn : callable
|
|
function called to round the result. Default: `round`.
|
|
epsilon : float
|
|
small value to add to the division result before rounding.
|
|
E.g., `0.3 / 0.1 = 2.9999999999999996`, when called with
|
|
`round_fn=math.floor` returns `2` instead of `3`. Adding a small value
|
|
to `0.3 / 0.1` avoids this error.
|
|
|
|
Returns
|
|
-------
|
|
nb_windows : int
|
|
minimum number of `analysis_window`'s to cover `durartion`. That means
|
|
that `analysis_window * nb_windows >= duration`.
|
|
"""
|
|
if duration < 0 or analysis_window <= 0:
|
|
err_msg = "'duration' ({}) must be >= 0 and 'analysis_window' ({}) > 0"
|
|
raise ValueError(err_msg.format(duration, analysis_window))
|
|
if duration == 0:
|
|
return 0
|
|
return int(round_fn(duration / analysis_window + epsilon))
|
|
|
|
|
|
def _make_audio_region(
|
|
data_frames,
|
|
start_frame,
|
|
frame_duration,
|
|
sampling_rate,
|
|
sample_width,
|
|
channels,
|
|
):
|
|
"""
|
|
Helper function to create an `AudioRegion` from parameters returned by
|
|
tokenization object. It takes care of setting up region `start` and `end`
|
|
in metadata.
|
|
|
|
Parameters
|
|
----------
|
|
frame_duration: float
|
|
duration of analysis window in seconds
|
|
start_frame : int
|
|
index of the fisrt analysis window
|
|
samling_rate : int
|
|
sampling rate of audio data
|
|
sample_width : int
|
|
number of bytes of one audio sample
|
|
channels : int
|
|
number of channels of audio data
|
|
|
|
Returns
|
|
-------
|
|
audio_region : AudioRegion
|
|
AudioRegion whose start time is calculeted as:
|
|
`1000 * start_frame * frame_duration`
|
|
"""
|
|
start = start_frame * frame_duration
|
|
data = b"".join(data_frames)
|
|
duration = len(data) / (sampling_rate * sample_width * channels)
|
|
meta = {"start": start, "end": start + duration}
|
|
return AudioRegion(data, sampling_rate, sample_width, channels, meta)
|
|
|
|
|
|
def _read_chunks_online(max_read, **kwargs):
|
|
"""
|
|
Helper function to read audio data from an online blocking source
|
|
(i.e., microphone). Used to build an `AudioRegion` and can intercept
|
|
KeyboardInterrupt so that reading stops as soon as this exception is
|
|
raised. Makes building `AudioRegion`s on [i]python sessions and jupyter
|
|
notebooks more user friendly.
|
|
|
|
Parameters
|
|
----------
|
|
max_read : float
|
|
maximum amount of data to read in seconds.
|
|
kwargs :
|
|
audio parameters (sampling_rate, sample_width and channels).
|
|
|
|
See also
|
|
--------
|
|
`AudioRegion.build`
|
|
"""
|
|
reader = AudioReader(None, block_dur=0.5, max_read=max_read, **kwargs)
|
|
reader.open()
|
|
data = []
|
|
try:
|
|
while True:
|
|
frame = reader.read()
|
|
if frame is None:
|
|
break
|
|
data.append(frame)
|
|
except KeyboardInterrupt:
|
|
# Stop data acquisition from microphone when pressing
|
|
# Ctrl+C on a [i]python session or a notebook
|
|
pass
|
|
reader.close()
|
|
return (
|
|
b"".join(data),
|
|
reader.sampling_rate,
|
|
reader.sample_width,
|
|
reader.channels,
|
|
)
|
|
|
|
|
|
def _read_offline(input, skip=0, max_read=None, **kwargs):
|
|
"""
|
|
Helper function to read audio data from an offline (i.e., file). Used to
|
|
build `AudioRegion`s.
|
|
|
|
Parameters
|
|
----------
|
|
input : str, bytes
|
|
path to audio file (if str), or a bytes object representing raw audio
|
|
data.
|
|
skip : float, default 0
|
|
amount of data to skip from the begining of audio source.
|
|
max_read : float, default: None
|
|
maximum amount of audio data to read. Default: None, means read until
|
|
end of stream.
|
|
kwargs :
|
|
audio parameters (sampling_rate, sample_width and channels).
|
|
|
|
See also
|
|
--------
|
|
`AudioRegion.build`
|
|
|
|
"""
|
|
audio_source = get_audio_source(input, **kwargs)
|
|
audio_source.open()
|
|
if skip is not None and skip > 0:
|
|
skip_samples = round(skip * audio_source.sampling_rate)
|
|
audio_source.read(skip_samples)
|
|
if max_read is not None:
|
|
if max_read < 0:
|
|
max_read = None
|
|
else:
|
|
max_read = round(max_read * audio_source.sampling_rate)
|
|
data = audio_source.read(max_read)
|
|
audio_source.close()
|
|
return (
|
|
data,
|
|
audio_source.sampling_rate,
|
|
audio_source.sample_width,
|
|
audio_source.channels,
|
|
)
|
|
|
|
|
|
def _check_convert_index(index, types, err_msg):
|
|
if not isinstance(index, slice) or index.step is not None:
|
|
raise TypeError(err_msg)
|
|
start = index.start if index.start is not None else 0
|
|
stop = index.stop
|
|
for index in (start, stop):
|
|
if index is not None and not isinstance(index, types):
|
|
raise TypeError(err_msg)
|
|
return start, stop
|
|
|
|
|
|
class _SecondsView:
|
|
"""A class to create a view of `AudioRegion` that can be sliced using
|
|
indices in seconds.
|
|
"""
|
|
|
|
def __init__(self, region):
|
|
self._region = region
|
|
|
|
def __getitem__(self, index):
|
|
err_msg = "Slicing AudioRegion by seconds requires indices of type "
|
|
err_msg += "'int' or 'float' without a step (e.g. region.sec[7.5:10])"
|
|
start_s, stop_s = _check_convert_index(index, (int, float), err_msg)
|
|
sr = self._region.sampling_rate
|
|
start_sample = int(start_s * sr)
|
|
stop_sample = None if stop_s is None else round(stop_s * sr)
|
|
return self._region[start_sample:stop_sample]
|
|
|
|
@property
|
|
def len(self):
|
|
"""
|
|
Return region duration in seconds.
|
|
"""
|
|
return self._region.duration
|
|
|
|
|
|
class _MillisView(_SecondsView):
|
|
"""A class to create a view of `AudioRegion` that can be sliced using
|
|
indices in milliseconds.
|
|
"""
|
|
|
|
def __getitem__(self, index):
|
|
err_msg = (
|
|
"Slicing AudioRegion by milliseconds requires indices of type "
|
|
)
|
|
err_msg += "'int' without a step (e.g. region.sec[500:1500])"
|
|
start_ms, stop_ms = _check_convert_index(index, (int), err_msg)
|
|
start_sec = start_ms / 1000
|
|
stop_sec = None if stop_ms is None else stop_ms / 1000
|
|
index = slice(start_sec, stop_sec)
|
|
return super(_MillisView, self).__getitem__(index)
|
|
|
|
def __len__(self):
|
|
"""
|
|
Return region duration in milliseconds.
|
|
"""
|
|
return round(self._region.duration * 1000)
|
|
|
|
@property
|
|
def len(self):
|
|
"""
|
|
Return region duration in milliseconds.
|
|
"""
|
|
return len(self)
|
|
|
|
|
|
class _AudioRegionMetadata(dict):
|
|
"""A class to store `AudioRegion`'s metadata."""
|
|
|
|
def __getattr__(self, name):
|
|
if name in self:
|
|
return self[name]
|
|
else:
|
|
err_msg = "AudioRegion metadata has no entry '{}'"
|
|
raise AttributeError(err_msg.format(name))
|
|
|
|
def __setattr__(self, name, value):
|
|
self[name] = value
|
|
|
|
def __str__(self):
|
|
return "\n".join("{}: {}".format(k, v) for k, v in self.items())
|
|
|
|
def __repr__(self):
|
|
return str(self)
|
|
|
|
|
|
class AudioRegion(object):
|
|
"""
|
|
AudioRegion encapsulates raw audio data and provides an interface to
|
|
perform simple operations on it. Use `AudioRegion.load` to build an
|
|
`AudioRegion` from different types of objects.
|
|
|
|
Parameters
|
|
----------
|
|
data : bytes
|
|
raw audio data as a bytes object
|
|
sampling_rate : int
|
|
sampling rate of audio data
|
|
sample_width : int
|
|
number of bytes of one audio sample
|
|
channels : int
|
|
number of channels of audio data
|
|
meta : dict, default: None
|
|
any collection of <key:value> elements used to build metadata for
|
|
this `AudioRegion`. Meta data can be accessed via `region.meta.key`
|
|
if `key` is a valid python attribute name, or via `region.meta[key]`
|
|
if not. Note that the :func:`split` function (or the
|
|
:meth:`AudioRegion.split` method) returns `AudioRegions` with a ``start``
|
|
and a ``stop`` meta values that indicate the location in seconds of the
|
|
region in original audio data.
|
|
|
|
See also
|
|
--------
|
|
AudioRegion.load
|
|
|
|
"""
|
|
|
|
def __init__(self, data, sampling_rate, sample_width, channels, meta=None):
|
|
check_audio_data(data, sample_width, channels)
|
|
self._data = data
|
|
self._sampling_rate = sampling_rate
|
|
self._sample_width = sample_width
|
|
self._channels = channels
|
|
self._samples = None
|
|
self.splitp = self.split_and_plot
|
|
|
|
if meta is not None:
|
|
self._meta = _AudioRegionMetadata(meta)
|
|
else:
|
|
self._meta = None
|
|
|
|
self._seconds_view = _SecondsView(self)
|
|
self.sec = self.seconds
|
|
self.s = self.seconds
|
|
|
|
self._millis_view = _MillisView(self)
|
|
self.ms = self.millis
|
|
|
|
@property
|
|
def meta(self):
|
|
return self._meta
|
|
|
|
@meta.setter
|
|
def meta(self, new_meta):
|
|
"""Meta data of audio region."""
|
|
self._meta = _AudioRegionMetadata(new_meta)
|
|
|
|
@classmethod
|
|
def load(cls, input, skip=0, max_read=None, **kwargs):
|
|
"""
|
|
Create an `AudioRegion` by loading data from `input`. See :func:`load`
|
|
for parameters descripion.
|
|
|
|
Returns
|
|
-------
|
|
region: AudioRegion
|
|
|
|
Raises
|
|
------
|
|
ValueError
|
|
raised if `input` is None and `skip` != 0 or `max_read` is None.
|
|
"""
|
|
if input is None:
|
|
if skip > 0:
|
|
raise ValueError(
|
|
"'skip' should be 0 when reading from microphone"
|
|
)
|
|
if max_read is None or max_read < 0:
|
|
raise ValueError(
|
|
"'max_read' should not be None when reading from "
|
|
"microphone"
|
|
)
|
|
data, sampling_rate, sample_width, channels = _read_chunks_online(
|
|
max_read, **kwargs
|
|
)
|
|
else:
|
|
data, sampling_rate, sample_width, channels = _read_offline(
|
|
input, skip=skip, max_read=max_read, **kwargs
|
|
)
|
|
|
|
return cls(data, sampling_rate, sample_width, channels)
|
|
|
|
@property
|
|
def seconds(self):
|
|
"""
|
|
A view to slice audio region by seconds (using ``region.seconds[start:end]``).
|
|
"""
|
|
return self._seconds_view
|
|
|
|
@property
|
|
def millis(self):
|
|
"""A view to slice audio region by milliseconds (using ``region.millis[start:end]``)."""
|
|
return self._millis_view
|
|
|
|
@property
|
|
def duration(self):
|
|
"""
|
|
Returns region duration in seconds.
|
|
"""
|
|
return len(self._data) / (
|
|
self.sampling_rate * self.sample_width * self.channels
|
|
)
|
|
|
|
@property
|
|
def sampling_rate(self):
|
|
"""Samling rate of audio data."""
|
|
return self._sampling_rate
|
|
|
|
@property
|
|
def sr(self):
|
|
"""Samling rate of audio data, alias for `sampling_rate`."""
|
|
return self._sampling_rate
|
|
|
|
@property
|
|
def sample_width(self):
|
|
"""Number of bytes per sample, one channel considered."""
|
|
return self._sample_width
|
|
|
|
@property
|
|
def sw(self):
|
|
"""Number of bytes per sample, alias for `sampling_rate`."""
|
|
return self._sample_width
|
|
|
|
@property
|
|
def channels(self):
|
|
"""Number of channels of audio data."""
|
|
return self._channels
|
|
|
|
@property
|
|
def ch(self):
|
|
"""Number of channels of audio data, alias for `channels`."""
|
|
return self._channels
|
|
|
|
def play(self, progress_bar=False, player=None, **progress_bar_kwargs):
|
|
"""
|
|
Play audio region.
|
|
|
|
Parameters
|
|
----------
|
|
progress_bar : bool, default: False
|
|
whether to use a progress bar while playing audio. Default: False.
|
|
`progress_bar` requires `tqdm`, if not installed, no progress bar
|
|
will be shown.
|
|
player : AudioPalyer, default: None
|
|
audio player to use. if None (default), use `player_for()`
|
|
to get a new audio player.
|
|
progress_bar_kwargs : kwargs
|
|
keyword arguments to pass to `tqdm` progress_bar builder (e.g.,
|
|
use `leave=False` to clean up the screen when play finishes).
|
|
"""
|
|
if player is None:
|
|
player = player_for(self)
|
|
player.play(
|
|
self._data, progress_bar=progress_bar, **progress_bar_kwargs
|
|
)
|
|
|
|
def save(self, file, audio_format=None, exists_ok=True, **audio_parameters):
|
|
"""
|
|
Save audio region to file.
|
|
|
|
Parameters
|
|
----------
|
|
file : str
|
|
path to output audio file. May contain `{duration}` placeholder
|
|
as well as any place holder that this region's metadata might
|
|
contain (e.g., regions returned by `split` contain metadata with
|
|
`start` and `end` attributes that can be used to build output file
|
|
name as `{meta.start}` and `{meta.end}`. See examples using
|
|
placeholders with formatting.
|
|
|
|
audio_format : str, default: None
|
|
format used to save audio data. If None (default), format is guessed
|
|
from file name's extension. If file name has no extension, audio
|
|
data is saved as a raw (headerless) audio file.
|
|
exists_ok : bool, default: True
|
|
If True, overwrite `file` if a file with the same name exists.
|
|
If False, raise an `IOError` if `file` exists.
|
|
audio_parameters: dict
|
|
any keyword arguments to be passed to audio saving backend.
|
|
|
|
Returns
|
|
-------
|
|
file: str
|
|
name of output file with replaced placehoders.
|
|
Raises
|
|
IOError if `file` exists and `exists_ok` is False.
|
|
|
|
|
|
Examples
|
|
--------
|
|
>>> region = AudioRegion(b'\\0' * 2 * 24000,
|
|
>>> sampling_rate=16000,
|
|
>>> sample_width=2,
|
|
>>> channels=1)
|
|
>>> region.meta.start = 2.25
|
|
>>> region.meta.end = 2.25 + region.duration
|
|
>>> region.save('audio_{meta.start}-{meta.end}.wav')
|
|
>>> audio_2.25-3.75.wav
|
|
>>> region.save('region_{meta.start:.3f}_{duration:.3f}.wav')
|
|
audio_2.250_1.500.wav
|
|
"""
|
|
if isinstance(file, str):
|
|
file = file.format(duration=self.duration, meta=self.meta)
|
|
if not exists_ok and os.path.exists(file):
|
|
raise FileExistsError("file '{file}' exists".format(file=file))
|
|
to_file(
|
|
self._data,
|
|
file,
|
|
audio_format,
|
|
sr=self.sr,
|
|
sw=self.sw,
|
|
ch=self.ch,
|
|
audio_parameters=audio_parameters,
|
|
)
|
|
return file
|
|
|
|
def split(
|
|
self,
|
|
min_dur=0.2,
|
|
max_dur=5,
|
|
max_silence=0.3,
|
|
drop_trailing_silence=False,
|
|
strict_min_dur=False,
|
|
**kwargs
|
|
):
|
|
"""Split audio region. See :func:`auditok.split()` for a comprehensive
|
|
description of split parameters.
|
|
See Also :meth:`AudioRegio.split_and_plot`.
|
|
"""
|
|
if kwargs.get("max_read", kwargs.get("mr")) is not None:
|
|
warn_msg = "'max_read' (or 'mr') should not be used with "
|
|
warn_msg += "AudioRegion.split_and_plot(). You should rather "
|
|
warn_msg += "slice audio region before calling this method"
|
|
raise RuntimeWarning(warn_msg)
|
|
return split(
|
|
self,
|
|
min_dur=min_dur,
|
|
max_dur=max_dur,
|
|
max_silence=max_silence,
|
|
drop_trailing_silence=drop_trailing_silence,
|
|
strict_min_dur=strict_min_dur,
|
|
**kwargs
|
|
)
|
|
|
|
def plot(
|
|
self,
|
|
scale_signal=True,
|
|
show=True,
|
|
figsize=None,
|
|
save_as=None,
|
|
dpi=120,
|
|
theme="auditok",
|
|
):
|
|
"""Plot audio region, one sub-plot for each channel.
|
|
|
|
Parameters
|
|
----------
|
|
scale_signal : bool, default: True
|
|
if true, scale signal by subtracting its mean and dividing by its
|
|
standard deviation before plotting.
|
|
show : bool
|
|
whether to show plotted signal right after the call.
|
|
figsize : tuple, default: None
|
|
width and height of the figure to pass to `matplotlib`.
|
|
save_as : str, default None.
|
|
if provided, also save plot to file.
|
|
dpi : int, default: 120
|
|
plot dpi to pass to `matplotlib`.
|
|
theme : str or dict, default: "auditok"
|
|
plot theme to use. Currently only "auditok" theme is implemented. To
|
|
provide you own them see :attr:`auditok.plotting.AUDITOK_PLOT_THEME`.
|
|
"""
|
|
try:
|
|
from auditok.plotting import plot
|
|
|
|
plot(
|
|
self,
|
|
scale_signal=scale_signal,
|
|
show=show,
|
|
figsize=figsize,
|
|
save_as=save_as,
|
|
dpi=dpi,
|
|
theme=theme,
|
|
)
|
|
except ImportError:
|
|
raise RuntimeWarning("Plotting requires matplotlib")
|
|
|
|
def split_and_plot(
|
|
self,
|
|
min_dur=0.2,
|
|
max_dur=5,
|
|
max_silence=0.3,
|
|
drop_trailing_silence=False,
|
|
strict_min_dur=False,
|
|
scale_signal=True,
|
|
show=True,
|
|
figsize=None,
|
|
save_as=None,
|
|
dpi=120,
|
|
theme="auditok",
|
|
**kwargs
|
|
):
|
|
"""Split region and plot signal and detections. Alias: :meth:`splitp`.
|
|
See :func:`auditok.split()` for a comprehensive description of split
|
|
parameters. Also see :meth:`plot` for plot parameters.
|
|
"""
|
|
try:
|
|
from auditok.plotting import plot
|
|
|
|
regions = self.split(
|
|
min_dur=min_dur,
|
|
max_dur=max_dur,
|
|
max_silence=max_silence,
|
|
drop_trailing_silence=drop_trailing_silence,
|
|
strict_min_dur=strict_min_dur,
|
|
**kwargs
|
|
)
|
|
regions = list(regions)
|
|
detections = ((reg.meta.start, reg.meta.end) for reg in regions)
|
|
eth = kwargs.get(
|
|
"energy_threshold", kwargs.get("eth", DEFAULT_ENERGY_THRESHOLD)
|
|
)
|
|
plot(
|
|
self,
|
|
scale_signal=scale_signal,
|
|
detections=detections,
|
|
energy_threshold=eth,
|
|
show=show,
|
|
figsize=figsize,
|
|
save_as=save_as,
|
|
dpi=dpi,
|
|
theme=theme,
|
|
)
|
|
return regions
|
|
except ImportError:
|
|
raise RuntimeWarning("Plotting requires matplotlib")
|
|
|
|
def __array__(self):
|
|
return self.samples
|
|
|
|
@property
|
|
def samples(self):
|
|
"""Audio region as arrays of samples, one array per channel."""
|
|
if self._samples is None:
|
|
self._samples = signal.to_array(
|
|
self._data, self.sample_width, self.channels
|
|
)
|
|
return self._samples
|
|
|
|
def __len__(self):
|
|
"""
|
|
Return region length in number of samples.
|
|
"""
|
|
return len(self._data) // (self.sample_width * self.channels)
|
|
|
|
@property
|
|
def len(self):
|
|
"""
|
|
Return region length in number of samples.
|
|
"""
|
|
return len(self)
|
|
|
|
def __bytes__(self):
|
|
return self._data
|
|
|
|
def __str__(self):
|
|
return (
|
|
"AudioRegion(duration={:.3f}, "
|
|
"sampling_rate={}, sample_width={}, channels={})".format(
|
|
self.duration, self.sr, self.sw, self.ch
|
|
)
|
|
)
|
|
|
|
def __repr__(self):
|
|
return str(self)
|
|
|
|
def __add__(self, other):
|
|
"""
|
|
Concatenates this region and `other` and return a new region.
|
|
Both regions must have the same sampling rate, sample width
|
|
and number of channels. If not, raises a `ValueError`.
|
|
"""
|
|
if not isinstance(other, AudioRegion):
|
|
raise TypeError(
|
|
"Can only concatenate AudioRegion, "
|
|
'not "{}"'.format(type(other))
|
|
)
|
|
if other.sr != self.sr:
|
|
raise ValueError(
|
|
"Can only concatenate AudioRegions of the same "
|
|
"sampling rate ({} != {})".format(self.sr, other.sr)
|
|
)
|
|
if other.sw != self.sw:
|
|
raise ValueError(
|
|
"Can only concatenate AudioRegions of the same "
|
|
"sample width ({} != {})".format(self.sw, other.sw)
|
|
)
|
|
if other.ch != self.ch:
|
|
raise ValueError(
|
|
"Can only concatenate AudioRegions of the same "
|
|
"number of channels ({} != {})".format(self.ch, other.ch)
|
|
)
|
|
data = self._data + other._data
|
|
return AudioRegion(data, self.sr, self.sw, self.ch)
|
|
|
|
def __radd__(self, other):
|
|
"""
|
|
Concatenates `other` and this region. `other` should be an
|
|
`AudioRegion` with the same audio parameters as this region
|
|
but can exceptionally be `0` to make it possible to concatenate
|
|
many regions with `sum`.
|
|
"""
|
|
if other == 0:
|
|
return self
|
|
return other.add(self)
|
|
|
|
def __mul__(self, n):
|
|
if not isinstance(n, int):
|
|
err_msg = "Can't multiply AudioRegion by a non-int of type '{}'"
|
|
raise TypeError(err_msg.format(type(n)))
|
|
data = self._data * n
|
|
return AudioRegion(data, self.sr, self.sw, self.ch)
|
|
|
|
def __rmul__(self, n):
|
|
return self * n
|
|
|
|
def __truediv__(self, n):
|
|
if not isinstance(n, int) or n <= 0:
|
|
raise TypeError("AudioRegion can only be divided by a positive int")
|
|
samples_per_sub_region, rest = divmod(len(self), n)
|
|
onset = 0
|
|
sub_regions = []
|
|
while onset < len(self):
|
|
offset = 0
|
|
if rest > 0:
|
|
offset = 1
|
|
rest -= 1
|
|
offset += onset + samples_per_sub_region
|
|
sub_regions.append(self[onset:offset])
|
|
onset = offset
|
|
return sub_regions
|
|
|
|
def __eq__(self, other):
|
|
if other is self:
|
|
return True
|
|
if not isinstance(other, AudioRegion):
|
|
return False
|
|
return (
|
|
(self._data == other._data)
|
|
and (self.sr == other.sr)
|
|
and (self.sw == other.sw)
|
|
and (self.ch == other.ch)
|
|
)
|
|
|
|
def __getitem__(self, index):
|
|
err_msg = "Slicing AudioRegion by samples requires indices of type "
|
|
err_msg += "'int' without a step (e.g. region.sec[1600:3200])"
|
|
start_sample, stop_sample = _check_convert_index(index, (int), err_msg)
|
|
|
|
bytes_per_sample = self.sample_width * self.channels
|
|
len_samples = len(self._data) // bytes_per_sample
|
|
|
|
if start_sample < 0:
|
|
start_sample = max(start_sample + len_samples, 0)
|
|
onset = start_sample * bytes_per_sample
|
|
|
|
if stop_sample is not None:
|
|
if stop_sample < 0:
|
|
stop_sample = max(stop_sample + len_samples, 0)
|
|
offset = index.stop * bytes_per_sample
|
|
else:
|
|
offset = None
|
|
|
|
data = self._data[onset:offset]
|
|
return AudioRegion(data, self.sr, self.sw, self.ch)
|
|
|
|
|
|
class StreamTokenizer:
|
|
"""
|
|
Class for stream tokenizers. It implements a 4-state automaton scheme
|
|
to extract sub-sequences of interest on the fly.
|
|
|
|
Parameters
|
|
----------
|
|
validator : callable, DataValidator (must implement `is_valid`)
|
|
called with each data frame read from source. Should take one positional
|
|
argument and return True or False for valid and invalid frames
|
|
respectively.
|
|
|
|
min_length : int
|
|
Minimum number of frames of a valid token. This includes all
|
|
tolerated non valid frames within the token.
|
|
|
|
max_length : int
|
|
Maximum number of frames of a valid token. This includes all
|
|
tolerated non valid frames within the token.
|
|
|
|
max_continuous_silence : int
|
|
Maximum number of consecutive non-valid frames within a token.
|
|
Note that, within a valid token, there may be many tolerated
|
|
*silent* regions that contain each a number of non valid frames up
|
|
to `max_continuous_silence`
|
|
|
|
init_min : int
|
|
Minimum number of consecutive valid frames that must be
|
|
**initially** gathered before any sequence of non valid frames can
|
|
be tolerated. This option is not always needed, it can be used to
|
|
drop non-valid tokens as early as possible. **Default = 0** means
|
|
that the option is by default ineffective.
|
|
|
|
init_max_silence : int
|
|
Maximum number of tolerated consecutive non-valid frames if the
|
|
number already gathered valid frames has not yet reached
|
|
'init_min'.This argument is normally used if `init_min` is used.
|
|
**Default = 0**, by default this argument is not taken into
|
|
consideration.
|
|
|
|
mode : int
|
|
mode can be one of the following:
|
|
|
|
-1 `StreamTokenizer.NORMAL` : do not drop trailing silence, and
|
|
accept a token shorter than `min_length` if it is the continuation
|
|
of the latest delivered token.
|
|
|
|
-2 `StreamTokenizer.STRICT_MIN_LENGTH`: if token `i` is delivered
|
|
because `max_length` is reached, and token `i+1` is immediately
|
|
adjacent to token `i` (i.e. token `i` ends at frame `k` and token
|
|
`i+1` starts at frame `k+1`) then accept token `i+1` only of it has
|
|
a size of at least `min_length`. The default behavior is to accept
|
|
token `i+1` event if it is shorter than `min_length` (provided that
|
|
the above conditions are fulfilled of course).
|
|
|
|
-3 `StreamTokenizer.DROP_TRAILING_SILENCE`: drop all tailing
|
|
non-valid frames from a token to be delivered if and only if it
|
|
is not **truncated**. This can be a bit tricky. A token is actually
|
|
delivered if:
|
|
|
|
- `max_continuous_silence` is reached.
|
|
|
|
- Its length reaches `max_length`. This is referred to as a
|
|
**truncated** token.
|
|
|
|
In the current implementation, a `StreamTokenizer`'s decision is only
|
|
based on already seen data and on incoming data. Thus, if a token is
|
|
truncated at a non-valid but tolerated frame (`max_length` is reached
|
|
but `max_continuous_silence` not yet) any tailing silence will be kept
|
|
because it can potentially be part of valid token (if `max_length` was
|
|
bigger). But if `max_continuous_silence` is reached before
|
|
`max_length`, the delivered token will not be considered as truncated
|
|
but a result of *normal* end of detection (i.e. no more valid data).
|
|
In that case the trailing silence can be removed if you use the
|
|
`StreamTokenizer.DROP_TRAILING_SILENCE` mode.
|
|
|
|
-4 `(StreamTokenizer.STRICT_MIN_LENGTH | StreamTokenizer.DROP_TRAILING_SILENCE)`:
|
|
use both options. That means: first remove tailing silence, then
|
|
check if the token still has a length of at least `min_length`.
|
|
|
|
|
|
|
|
|
|
Examples
|
|
--------
|
|
|
|
In the following code, without `STRICT_MIN_LENGTH`, the 'BB' token is
|
|
accepted although it is shorter than `min_length` (3), because it
|
|
immediately follows the latest delivered token:
|
|
|
|
>>> from auditok.core import StreamTokenizer
|
|
>>> from StringDataSource, DataValidator
|
|
|
|
>>> class UpperCaseChecker(DataValidator):
|
|
>>> def is_valid(self, frame):
|
|
return frame.isupper()
|
|
>>> dsource = StringDataSource("aaaAAAABBbbb")
|
|
>>> tokenizer = StreamTokenizer(validator=UpperCaseChecker(),
|
|
min_length=3,
|
|
max_length=4,
|
|
max_continuous_silence=0)
|
|
>>> tokenizer.tokenize(dsource)
|
|
[(['A', 'A', 'A', 'A'], 3, 6), (['B', 'B'], 7, 8)]
|
|
|
|
|
|
The following tokenizer will however reject the 'BB' token:
|
|
|
|
>>> dsource = StringDataSource("aaaAAAABBbbb")
|
|
>>> tokenizer = StreamTokenizer(validator=UpperCaseChecker(),
|
|
min_length=3, max_length=4,
|
|
max_continuous_silence=0,
|
|
mode=StreamTokenizer.STRICT_MIN_LENGTH)
|
|
>>> tokenizer.tokenize(dsource)
|
|
[(['A', 'A', 'A', 'A'], 3, 6)]
|
|
|
|
|
|
|
|
>>> tokenizer = StreamTokenizer(
|
|
>>> validator=UpperCaseChecker(),
|
|
>>> min_length=3,
|
|
>>> max_length=6,
|
|
>>> max_continuous_silence=3,
|
|
>>> mode=StreamTokenizer.DROP_TRAILING_SILENCE
|
|
>>> )
|
|
>>> dsource = StringDataSource("aaaAAAaaaBBbbbb")
|
|
>>> tokenizer.tokenize(dsource)
|
|
[(['A', 'A', 'A', 'a', 'a', 'a'], 3, 8), (['B', 'B'], 9, 10)]
|
|
|
|
The first token is delivered with its tailing silence because it is
|
|
truncated while the second one has its tailing frames removed.
|
|
|
|
Without `StreamTokenizer.DROP_TRAILING_SILENCE` the output would be:
|
|
|
|
.. code:: python
|
|
|
|
[
|
|
(['A', 'A', 'A', 'a', 'a', 'a'], 3, 8),
|
|
(['B', 'B', 'b', 'b', 'b'], 9, 13)
|
|
]
|
|
|
|
"""
|
|
|
|
SILENCE = 0
|
|
POSSIBLE_SILENCE = 1
|
|
POSSIBLE_NOISE = 2
|
|
NOISE = 3
|
|
NORMAL = 0
|
|
STRICT_MIN_LENGTH = 2
|
|
DROP_TRAILING_SILENCE = 4
|
|
|
|
def __init__(
|
|
self,
|
|
validator,
|
|
min_length,
|
|
max_length,
|
|
max_continuous_silence,
|
|
init_min=0,
|
|
init_max_silence=0,
|
|
mode=0,
|
|
):
|
|
if callable(validator):
|
|
self._is_valid = validator
|
|
elif isinstance(validator, DataValidator):
|
|
self._is_valid = validator.is_valid
|
|
else:
|
|
raise TypeError(
|
|
"'validator' must be a callable or an instance of "
|
|
"DataValidator"
|
|
)
|
|
|
|
if max_length <= 0:
|
|
raise ValueError(
|
|
"'max_length' must be > 0 (value={0})".format(max_length)
|
|
)
|
|
|
|
if min_length <= 0 or min_length > max_length:
|
|
err_msg = "'min_length' must be > 0 and <= 'max_length' (value={0})"
|
|
raise ValueError(err_msg.format(min_length))
|
|
|
|
if max_continuous_silence >= max_length:
|
|
err_msg = "'max_continuous_silence' must be < 'max_length' "
|
|
err_msg += "(value={0})"
|
|
raise ValueError(err_msg.format(max_continuous_silence))
|
|
|
|
if init_min >= max_length:
|
|
raise ValueError(
|
|
"'init_min' must be < 'max_length' (value={0})".format(
|
|
max_continuous_silence
|
|
)
|
|
)
|
|
|
|
self.validator = validator
|
|
self.min_length = min_length
|
|
self.max_length = max_length
|
|
self.max_continuous_silence = max_continuous_silence
|
|
self.init_min = init_min
|
|
self.init_max_silent = init_max_silence
|
|
self._set_mode(mode)
|
|
self._deliver = None
|
|
self._tokens = None
|
|
self._state = None
|
|
self._data = None
|
|
self._contiguous_token = False
|
|
self._init_count = 0
|
|
self._silence_length = 0
|
|
self._start_frame = 0
|
|
self._current_frame = 0
|
|
|
|
def _set_mode(self, mode):
|
|
strict_min_and_drop_trailing = StreamTokenizer.STRICT_MIN_LENGTH
|
|
strict_min_and_drop_trailing |= StreamTokenizer.DROP_TRAILING_SILENCE
|
|
if mode not in [
|
|
StreamTokenizer.NORMAL,
|
|
StreamTokenizer.STRICT_MIN_LENGTH,
|
|
StreamTokenizer.DROP_TRAILING_SILENCE,
|
|
strict_min_and_drop_trailing,
|
|
]:
|
|
raise ValueError("Wrong value for mode")
|
|
self._mode = mode
|
|
self._strict_min_length = (mode & self.STRICT_MIN_LENGTH) != 0
|
|
self._drop_trailing_silence = (mode & self.DROP_TRAILING_SILENCE) != 0
|
|
|
|
def _reinitialize(self):
|
|
self._contiguous_token = False
|
|
self._data = []
|
|
self._tokens = []
|
|
self._state = self.SILENCE
|
|
self._current_frame = -1
|
|
self._deliver = self._append_token
|
|
|
|
def tokenize(self, data_source, callback=None, generator=False):
|
|
"""
|
|
Read data from `data_source`, one frame a time, and process the read
|
|
frames in order to detect sequences of frames that make up valid
|
|
tokens.
|
|
|
|
:Parameters:
|
|
`data_source` : instance of the :class:`DataSource` class that
|
|
implements a `read` method. 'read' should return a slice of
|
|
signal, i.e. frame (of whatever type as long as it can be
|
|
processed by validator) and None if there is no more signal.
|
|
|
|
`callback` : an optional 3-argument function.
|
|
If a `callback` function is given, it will be called each time
|
|
a valid token is found.
|
|
|
|
|
|
:Returns:
|
|
A list of tokens if `callback` is None. Each token is tuple with the
|
|
following elements:
|
|
|
|
.. code python
|
|
|
|
(data, start, end)
|
|
|
|
where `data` is a list of read frames, `start`: index of the first
|
|
frame in the original data and `end` : index of the last frame.
|
|
"""
|
|
token_gen = self._iter_tokens(data_source)
|
|
if callback:
|
|
for token in token_gen:
|
|
callback(*token)
|
|
return
|
|
if generator:
|
|
return token_gen
|
|
return list(token_gen)
|
|
|
|
def _iter_tokens(self, data_source):
|
|
self._reinitialize()
|
|
while True:
|
|
frame = data_source.read()
|
|
self._current_frame += 1
|
|
if frame is None:
|
|
token = self._post_process()
|
|
if token is not None:
|
|
yield token
|
|
break
|
|
token = self._process(frame)
|
|
if token is not None:
|
|
yield token
|
|
|
|
def _process(self, frame): # noqa: C901
|
|
|
|
frame_is_valid = self._is_valid(frame)
|
|
|
|
if self._state == self.SILENCE:
|
|
|
|
if frame_is_valid:
|
|
# seems we got a valid frame after a silence
|
|
self._init_count = 1
|
|
self._silence_length = 0
|
|
self._start_frame = self._current_frame
|
|
self._data.append(frame)
|
|
|
|
if self._init_count >= self.init_min:
|
|
self._state = self.NOISE
|
|
if len(self._data) >= self.max_length:
|
|
return self._process_end_of_detection(True)
|
|
else:
|
|
self._state = self.POSSIBLE_NOISE
|
|
|
|
elif self._state == self.POSSIBLE_NOISE:
|
|
|
|
if frame_is_valid:
|
|
self._silence_length = 0
|
|
self._init_count += 1
|
|
self._data.append(frame)
|
|
if self._init_count >= self.init_min:
|
|
self._state = self.NOISE
|
|
if len(self._data) >= self.max_length:
|
|
return self._process_end_of_detection(True)
|
|
|
|
else:
|
|
self._silence_length += 1
|
|
if (
|
|
self._silence_length > self.init_max_silent
|
|
or len(self._data) + 1 >= self.max_length
|
|
):
|
|
# either init_max_silent or max_length is reached
|
|
# before _init_count, back to silence
|
|
self._data = []
|
|
self._state = self.SILENCE
|
|
else:
|
|
self._data.append(frame)
|
|
|
|
elif self._state == self.NOISE:
|
|
|
|
if frame_is_valid:
|
|
self._data.append(frame)
|
|
if len(self._data) >= self.max_length:
|
|
return self._process_end_of_detection(True)
|
|
|
|
elif self.max_continuous_silence <= 0:
|
|
# max token reached at this frame will _deliver if
|
|
# _contiguous_token and not _strict_min_length
|
|
self._state = self.SILENCE
|
|
return self._process_end_of_detection()
|
|
else:
|
|
# this is the first silent frame following a valid one
|
|
# and it is tolerated
|
|
self._silence_length = 1
|
|
self._data.append(frame)
|
|
self._state = self.POSSIBLE_SILENCE
|
|
if len(self._data) == self.max_length:
|
|
return self._process_end_of_detection(True)
|
|
# don't reset _silence_length because we still
|
|
# need to know the total number of silent frames
|
|
|
|
elif self._state == self.POSSIBLE_SILENCE:
|
|
|
|
if frame_is_valid:
|
|
self._data.append(frame)
|
|
self._silence_length = 0
|
|
self._state = self.NOISE
|
|
if len(self._data) >= self.max_length:
|
|
return self._process_end_of_detection(True)
|
|
|
|
else:
|
|
if self._silence_length >= self.max_continuous_silence:
|
|
self._state = self.SILENCE
|
|
if self._silence_length < len(self._data):
|
|
# _deliver only gathered frames aren't all silent
|
|
return self._process_end_of_detection()
|
|
self._data = []
|
|
self._silence_length = 0
|
|
else:
|
|
self._data.append(frame)
|
|
self._silence_length += 1
|
|
if len(self._data) >= self.max_length:
|
|
return self._process_end_of_detection(True)
|
|
# don't reset _silence_length because we still
|
|
# need to know the total number of silent frames
|
|
|
|
def _post_process(self):
|
|
if self._state == self.NOISE or self._state == self.POSSIBLE_SILENCE:
|
|
if len(self._data) > 0 and len(self._data) > self._silence_length:
|
|
return self._process_end_of_detection()
|
|
|
|
def _process_end_of_detection(self, truncated=False):
|
|
|
|
if (
|
|
not truncated
|
|
and self._drop_trailing_silence
|
|
and self._silence_length > 0
|
|
):
|
|
# happens if max_continuous_silence is reached
|
|
# or max_length is reached at a silent frame
|
|
self._data = self._data[0 : -self._silence_length]
|
|
|
|
if (len(self._data) >= self.min_length) or (
|
|
len(self._data) > 0
|
|
and not self._strict_min_length
|
|
and self._contiguous_token
|
|
):
|
|
|
|
start_frame = self._start_frame
|
|
end_frame = self._start_frame + len(self._data) - 1
|
|
data = self._data
|
|
self._data = []
|
|
token = (data, start_frame, end_frame)
|
|
|
|
if truncated:
|
|
# next token (if any) will start at _current_frame + 1
|
|
self._start_frame = self._current_frame + 1
|
|
# remember that it is contiguous with the just delivered one
|
|
self._contiguous_token = True
|
|
else:
|
|
self._contiguous_token = False
|
|
return token
|
|
else:
|
|
self._contiguous_token = False
|
|
|
|
self._data = []
|
|
|
|
def _append_token(self, data, start, end):
|
|
self._tokens.append((data, start, end))
|