Upgraded vendored Python dependencies to the latest versions and removed the unused dependencies.v1.0.3-beta.16

12 files changed, 4572 insertions, 2225 deletions

diff --git a/libs/auditok/__init__.py b/libs/auditok/__init__.py
index 4ea697b77..edd336cc3 100644
--- a/libs/auditok/__init__.py
+++ b/libs/auditok/__init__.py
@@ -2,20 +2,16 @@
 :author:
 
 Amine SEHILI <[email protected]>
-2015-2016
+2015-2021
 
 :License:
 
-This package is published under GNU GPL Version 3.
+This package is published under the MIT license.
 """
 
-from __future__ import absolute_import
 from .core import *
 from .io import *
 from .util import *
-from . import dataset
 from .exceptions import *
 
-__version__ = "0.1.5"
-
-
+__version__ = "0.2.0"
diff --git a/libs/auditok/cmdline.py b/libs/auditok/cmdline.py
index b6a51d11b..7e7450762 100755
--- a/libs/auditok/cmdline.py
+++ b/libs/auditok/cmdline.py
@@ -1,789 +1,428 @@
 #!/usr/bin/env python
 # encoding: utf-8
-'''
-auditok.auditok -- Audio Activity Detection tool
-
-auditok.auditok is a program that can be used for Audio/Acoustic activity detection.
-It can read audio data from audio files as well as from built-in device(s) or standard input 
+"""
+`auditok` -- An Audio Activity Detection tool
 
+`auditok` is a program that can be used for Audio/Acoustic
+activity detection. It can read audio data from audio files as well
+as from the microphone or standard input.
 
 @author:     Mohamed El Amine SEHILI
-
-@copyright:  2015 Mohamed El Amine SEHILI
-
-@license:    GPL v3
-
+@copyright:  2015-2021 Mohamed El Amine SEHILI
+@license:    MIT
 @contact:    [email protected]
-@deffield    updated: 02 Dec 2015
-'''
+@deffield    updated: 01 Mar 2021
+"""
 
 import sys
 import os
-
-from optparse import OptionParser, OptionGroup
-from threading import Thread
-import tempfile
-import wave
+from argparse import ArgumentParser
 import time
 import threading
-import logging
 
-try:
-    import future
-    from queue import Queue, Empty
-except ImportError:
-    if sys.version_info >= (3, 0):
-        from queue import Queue, Empty
-    else:
-        from Queue import Queue, Empty
+from auditok import __version__, AudioRegion
+from .util import AudioDataSource
+from .exceptions import EndOfProcessing, AudioEncodingWarning
+from .io import player_for
+from .cmdline_util import make_logger, make_kwargs, initialize_workers
+from . import workers
 
-try:
-    from pydub import AudioSegment
-    WITH_PYDUB = True
-except ImportError:
-    WITH_PYDUB = False
-    
-
-from .core import StreamTokenizer
-from .io import PyAudioSource, BufferAudioSource, StdinAudioSource, player_for
-from .util import ADSFactory, AudioEnergyValidator
-from auditok import __version__ as version
 
 __all__ = []
-__version__ = version
-__date__ = '2015-11-23'
-__updated__ = '2015-03-11'
-
-DEBUG = 0
-TESTRUN = 1
-PROFILE = 0
-
-LOGGER_NAME = "AUDITOK_LOGGER"
-
-class AudioFileFormatError(Exception):
-    pass
-
-class TimeFormatError(Exception):
-    pass
-
-def file_to_audio_source(filename, filetype=None, **kwargs):
-    
-    lower_fname = filename.lower()
-    rawdata = False
-    
-    if filetype is not None:
-        filetype = filetype.lower()
-    
-    if filetype == "raw" or (filetype is None and lower_fname.endswith(".raw")):
-        
-        srate = kwargs.pop("sampling_rate", None)
-        if srate is None:
-            srate = kwargs.pop("sr", None)
-            
-        swidth = kwargs.pop("sample_width", None)
-        if swidth is None:
-            swidth = kwargs.pop("sw", None)
-        
-        ch = kwargs.pop("channels", None)
-        if ch is None:
-            ch = kwargs.pop("ch", None)
-        
-        if None in (swidth, srate, ch):
-            raise Exception("All audio parameters are required for raw data") 
-        
-        data = open(filename).read()
-        rawdata = True
-        
-    # try first with pydub
-    if WITH_PYDUB:
-        
-        use_channel = kwargs.pop("use_channel", None)
-        if use_channel is None:
-            use_channel = kwargs.pop("uc", None)
-        
-        if use_channel is None:
-            use_channel = 1
-        else:
-            try:
-                use_channel = int(use_channel)
-            except ValueError:
-                pass
-        
-        if not isinstance(use_channel, (int)) and not use_channel.lower() in ["left", "right", "mix"] :
-            raise ValueError("channel must be an integer or one of 'left', 'right' or 'mix'")
-        
-        asegment = None
-        
-        if rawdata:
-            asegment = AudioSegment(data, sample_width=swidth, frame_rate=srate, channels=ch)
-        if filetype in("wave", "wav") or (filetype is None and lower_fname.endswith(".wav")):
-            asegment = AudioSegment.from_wav(filename)
-        elif filetype == "mp3" or (filetype is None and lower_fname.endswith(".mp3")):
-            asegment = AudioSegment.from_mp3(filename)
-        elif filetype == "ogg" or (filetype is None and lower_fname.endswith(".ogg")):
-            asegment = AudioSegment.from_ogg(filename)
-        elif filetype == "flv" or (filetype is None and lower_fname.endswith(".flv")):
-            asegment = AudioSegment.from_flv(filename)
-        else:
-            asegment = AudioSegment.from_file(filename)
-            
-        if asegment.channels > 1:
-            
-            if isinstance(use_channel, int):
-                if use_channel > asegment.channels:
-                    raise ValueError("Can not use channel '{0}', audio file has only {1} channels".format(use_channel, asegment.channels))
-                else:
-                    asegment = asegment.split_to_mono()[use_channel - 1]
-            else:
-                ch_lower = use_channel.lower()
-                
-                if ch_lower == "mix":
-                    asegment = asegment.set_channels(1)
-                    
-                elif use_channel.lower() == "left":
-                    asegment = asegment.split_to_mono()[0]
-                    
-                elif use_channel.lower() == "right":
-                    asegment = asegment.split_to_mono()[1]
-        
-        return BufferAudioSource(data_buffer = asegment._data,
-                                     sampling_rate = asegment.frame_rate,
-                                     sample_width = asegment.sample_width,
-                                     channels = asegment.channels)
-    # fall back to standard python
-    else:
-        if rawdata:
-            if ch != 1:
-                raise ValueError("Cannot handle multi-channel audio without pydub")
-            return BufferAudioSource(data, srate, swidth, ch)
-    
-        if filetype in ("wav", "wave") or (filetype is None and lower_fname.endswith(".wav")):
-            
-            wfp = wave.open(filename)
-            
-            ch = wfp.getnchannels()
-            if ch != 1:
-                wfp.close()
-                raise ValueError("Cannot handle multi-channel audio without pydub")
-           
-            srate = wfp.getframerate()
-            swidth = wfp.getsampwidth()
-            data = wfp.readframes(wfp.getnframes())
-            wfp.close()
-            return BufferAudioSource(data, srate, swidth, ch)
-        
-        raise AudioFileFormatError("Cannot read audio file format")
-
-
-def save_audio_data(data, filename, filetype=None, **kwargs):
-    
-    lower_fname = filename.lower()
-    if filetype is not None:
-        filetype = filetype.lower()
-        
-    # save raw data
-    if filetype == "raw" or (filetype is None and lower_fname.endswith(".raw")):
-        fp = open(filename, "w")
-        fp.write(data)
-        fp.close()
-        return
-    
-    # save other types of data
-    # requires all audio parameters
-    srate = kwargs.pop("sampling_rate", None)
-    if srate is None:
-        srate = kwargs.pop("sr", None)
-        
-    swidth = kwargs.pop("sample_width", None)
-    if swidth is None:
-        swidth = kwargs.pop("sw", None)
-    
-    ch = kwargs.pop("channels", None)
-    if ch is None:
-        ch = kwargs.pop("ch", None)
-    
-    if None in (swidth, srate, ch):
-        raise Exception("All audio parameters are required to save no raw data")
-        
-    if filetype in ("wav", "wave") or (filetype is None and lower_fname.endswith(".wav")):
-        # use standard python's wave module
-        fp = wave.open(filename, "w")
-        fp.setnchannels(ch)
-        fp.setsampwidth(swidth)
-        fp.setframerate(srate)
-        fp.writeframes(data)
-        fp.close()
-    
-    elif WITH_PYDUB:
-        
-        asegment = AudioSegment(data, sample_width=swidth, frame_rate=srate, channels=ch)
-        asegment.export(filename, format=filetype)
-    
-    else:
-        raise AudioFileFormatError("cannot write file format {0} (file name: {1})".format(filetype, filename))
-
-
-def plot_all(signal, sampling_rate, energy_as_amp, detections=[], show=True, save_as=None):
-    
-    import matplotlib.pyplot as plt
-    import numpy as np
-    t = np.arange(0., np.ceil(float(len(signal))) / sampling_rate, 1./sampling_rate )
-    if len(t) > len(signal):
-        t = t[: len(signal) - len(t)]
-    
-    for start, end in detections:
-        p = plt.axvspan(start, end, facecolor='g', ec = 'r', lw = 2,  alpha=0.4)
-    
-    line = plt.axhline(y=energy_as_amp, lw=1, ls="--", c="r", label="Energy threshold as normalized amplitude")
-    plt.plot(t, signal)
-    legend = plt.legend(["Detection threshold"], bbox_to_anchor=(0., 1.02, 1., .102), loc=1, fontsize=16)
-    ax = plt.gca().add_artist(legend)
-
-    plt.xlabel("Time (s)", fontsize=24)
-    plt.ylabel("Amplitude (normalized)", fontsize=24)
-    
-    if save_as is not None:
-        plt.savefig(save_as, dpi=120)
-    
-    if show:
-        plt.show()
-
-
-def seconds_to_str_fromatter(_format):
-    """
-    Accepted format directives: %i %s %m %h
-    """
-    # check directives are correct 
-    
-    if _format == "%S":
-        def _fromatter(seconds):
-            return "{:.2f}".format(seconds)
-    
-    elif _format == "%I":
-        def _fromatter(seconds):
-            return "{0}".format(int(seconds * 1000))
-    
-    else:
-        _format = _format.replace("%h", "{hrs:02d}")
-        _format = _format.replace("%m", "{mins:02d}")
-        _format = _format.replace("%s", "{secs:02d}")
-        _format = _format.replace("%i", "{millis:03d}")
-        
-        try:
-            i = _format.index("%")
-            raise TimeFormatError("Unknow time format directive '{0}'".format(_format[i:i+2]))
-        except ValueError:
-            pass
-        
-        def _fromatter(seconds):
-            millis = int(seconds * 1000)
-            hrs, millis = divmod(millis, 3600000)
-            mins, millis = divmod(millis, 60000)
-            secs, millis = divmod(millis, 1000)
-            return _format.format(hrs=hrs, mins=mins, secs=secs, millis=millis)
-    
-    return _fromatter
-
-
-
-class Worker(Thread):
-    
-    def __init__(self, timeout=0.2, debug=False, logger=None):
-        self.timeout = timeout
-        self.debug = debug
-        self.logger = logger
-        
-        if self.debug and self.logger is None:
-            self.logger = logging.getLogger(LOGGER_NAME)
-            self.logger.setLevel(logging.DEBUG)
-            handler = logging.StreamHandler(sys.stdout)
-            self.logger.addHandler(handler)
-            
-        self._inbox = Queue()
-        self._stop_request = Queue()
-        Thread.__init__(self)
-    
-    
-    def debug_message(self, message):
-        self.logger.debug(message)
-        
-    def _stop_requested(self):
-        
-        try:
-            message = self._stop_request.get_nowait()
-            if message == "stop":
-                return True
-
-        except Empty:
-            return False
-    
-    def stop(self):
-        self._stop_request.put("stop")
-        self.join()
-        
-    def send(self, message):
-        self._inbox.put(message)
-    
-    def _get_message(self):
-        try:
-            message = self._inbox.get(timeout=self.timeout)
-            return message        
-        except Empty:
-            return None
-
-
-class TokenizerWorker(Worker):
-    
-    END_OF_PROCESSING = "END_OF_PROCESSING"
-    
-    def __init__(self, ads, tokenizer, analysis_window, observers):
-        self.ads = ads
-        self.tokenizer = tokenizer
-        self.analysis_window = analysis_window
-        self.observers = observers
-        self._inbox = Queue()
-        self.count = 0
-        Worker.__init__(self)
-        
-    def run(self):
-        
-        def notify_observers(data, start, end):
-            audio_data = b''.join(data)
-            self.count += 1
-            
-            start_time = start * self.analysis_window
-            end_time = (end+1) * self.analysis_window
-            duration = (end - start + 1) * self.analysis_window
-            
-            # notify observers
-            for observer in self.observers:
-                observer.notify({"id" : self.count,
-                                 "audio_data" : audio_data,
-                                 "start" : start,
-                                 "end" : end,
-                                 "start_time" : start_time,
-                                 "end_time" : end_time,
-                                 "duration" : duration}
-                                )
-        
-        self.ads.open()
-        self.tokenizer.tokenize(data_source=self, callback=notify_observers)
-        for observer in self.observers:
-            observer.notify(TokenizerWorker.END_OF_PROCESSING)
-            
-    def add_observer(self, observer):
-        self.observers.append(observer)
-       
-    def remove_observer(self, observer):
-        self.observers.remove(observer)
-    
-    def read(self):
-        if self._stop_requested():
-            return None
-        else:
-            return self.ads.read()
-    
-        
-class PlayerWorker(Worker):
-    
-    def __init__(self, player, timeout=0.2, debug=False, logger=None):
-        self.player = player
-        Worker.__init__(self, timeout=timeout, debug=debug, logger=logger)
-        
-    def run(self):
-        while True:
-            if self._stop_requested():
-                break
-            
-            message = self._get_message()
-            if message is not None:
-                if message == TokenizerWorker.END_OF_PROCESSING:
-                    break
-                
-                audio_data = message.pop("audio_data", None)
-                start_time = message.pop("start_time", None)
-                end_time = message.pop("end_time", None)
-                dur = message.pop("duration", None)
-                _id = message.pop("id", None)
-                
-                if audio_data is not None:
-                    if self.debug:
-                        self.debug_message("[PLAY]: Detection {id} played (start:{start}, end:{end}, dur:{dur})".format(id=_id, 
-                        start="{:5.2f}".format(start_time), end="{:5.2f}".format(end_time), dur="{:5.2f}".format(dur)))
-                    self.player.play(audio_data)
-    
-    def notify(self, message):
-        self.send(message)
-        
-               
-class CommandLineWorker(Worker):
-    
-    def __init__(self, command, timeout=0.2, debug=False, logger=None):
-        self.command = command
-        Worker.__init__(self, timeout=timeout, debug=debug, logger=logger)
-    
-    def run(self):
-        while True:
-            if self._stop_requested():
-                break
-            
-            message = self._get_message()
-            if message is not None:
-                if message == TokenizerWorker.END_OF_PROCESSING:
-                    break
-                
-                audio_data = message.pop("audio_data", None)
-                _id = message.pop("id", None)
-                if audio_data is not None:
-                    raw_audio_file = tempfile.NamedTemporaryFile(delete=False)
-                    raw_audio_file.write(audio_data)
-                    cmd = self.command.replace("$", raw_audio_file.name)
-                    if self.debug:
-                        self.debug_message("[CMD ]: Detection {id} command: {cmd}".format(id=_id, cmd=cmd))
-                    os.system(cmd)
-                    os.unlink(raw_audio_file.name)
-                
-    def notify(self, message):
-        self.send(message)
-        
-
-class TokenSaverWorker(Worker):
-    
-    def __init__(self, name_format, filetype, timeout=0.2, debug=False, logger=None, **kwargs):
-        self.name_format = name_format
-        self.filetype = filetype
-        self.kwargs = kwargs
-        Worker.__init__(self, timeout=timeout, debug=debug, logger=logger)
-    
-    def run(self):
-        while True:
-            if self._stop_requested():
-                break
-            
-            message = self._get_message()
-            if message is not None:
-                if message == TokenizerWorker.END_OF_PROCESSING:
-                    break
-                
-                audio_data = message.pop("audio_data", None)
-                start_time = message.pop("start_time", None)
-                end_time = message.pop("end_time", None)
-                _id = message.pop("id", None)
-                if audio_data is not None and len(audio_data) > 0:
-                    fname = self.name_format.format(N=_id, start = "{:.2f}".format(start_time), end = "{:.2f}".format(end_time))
-                    try:
-                        if self.debug:
-                            self.debug_message("[SAVE]: Detection {id} saved as {fname}".format(id=_id, fname=fname))
-                        save_audio_data(audio_data, fname, filetype=self.filetype, **self.kwargs)
-                    except Exception as e:
-                        sys.stderr.write(str(e) + "\n")
-    
-    def notify(self, message):
-        self.send(message)
-
-
-class LogWorker(Worker):
-    
-    def __init__(self, print_detections=False, output_format="{start} {end}",
-                 time_formatter=seconds_to_str_fromatter("%S"), timeout=0.2, debug=False, logger=None):
-        
-        self.print_detections = print_detections
-        self.output_format = output_format
-        self.time_formatter = time_formatter
-        self.detections = []
-        Worker.__init__(self, timeout=timeout, debug=debug, logger=logger)
-        
-    def run(self):
-        while True:
-            if self._stop_requested():
-                break
-            
-            message = self._get_message()
-            
-            if message is not None:
-                
-                if message == TokenizerWorker.END_OF_PROCESSING:
-                    break
-                
-                audio_data = message.pop("audio_data", None)
-                _id = message.pop("id", None)
-                start = message.pop("start", None)
-                end = message.pop("end", None)
-                start_time = message.pop("start_time", None)
-                end_time = message.pop("end_time", None)
-                if audio_data is not None and len(audio_data) > 0:
-                    
-                    if self.debug:
-                        self.debug_message("[DET ]: Detection {id} (start:{start}, end:{end})".format(id=_id, 
-                            start="{:5.2f}".format(start_time),
-                            end="{:5.2f}".format(end_time)))
-                    
-                    if self.print_detections:
-                        print(self.output_format.format(id = _id,
-                            start = self.time_formatter(start_time),
-                            end = self.time_formatter(end_time)))
-                        
-                    self.detections.append((_id, start, end, start_time, end_time))
-                   
-    
-    def notify(self, message):
-        self.send(message)
-
+__date__ = "2015-11-23"
+__updated__ = "2021-03-01"
 
 
 def main(argv=None):
-    '''Command line options.'''
-
     program_name = os.path.basename(sys.argv[0])
-    program_version = version
-    program_build_date = "%s" % __updated__
-
-    program_version_string = '%%prog %s (%s)' % (program_version, program_build_date)
-    #program_usage = '''usage: spam two eggs''' # optional - will be autogenerated by optparse
-    program_longdesc = '''''' # optional - give further explanation about what the program does
-    program_license = "Copyright 2015 Mohamed El Amine SEHILI                                            \
-                Licensed under the General Public License (GPL) Version 3 \nhttp://www.gnu.org/licenses/"
-
     if argv is None:
         argv = sys.argv[1:]
     try:
-        # setup option parser
-        parser = OptionParser(version=program_version_string, epilog=program_longdesc, description=program_license)
-        
-        group = OptionGroup(parser, "[Input-Output options]")
-        group.add_option("-i", "--input", dest="input", help="Input audio or video file. Use - for stdin [default: read from microphone using pyaudio]", metavar="FILE")
-        group.add_option("-t", "--input-type", dest="input_type", help="Input audio file type. Mandatory if file name has no extension [default: %default]", type=str, default=None, metavar="String")
-        group.add_option("-M", "--max_time", dest="max_time", help="Max data (in seconds) to read from microphone/file [default: read until the end of file/stream]", type=float, default=None, metavar="FLOAT")
-        group.add_option("-O", "--output-main", dest="output_main", help="Save main stream as. If omitted main stream will not be saved [default: omitted]", type=str, default=None, metavar="FILE")
-        group.add_option("-o", "--output-tokens", dest="output_tokens", help="Output file name format for detections. Use {N} and {start} and {end} to build file names, example: 'Det_{N}_{start}-{end}.wav'", type=str, default=None, metavar="STRING")
-        group.add_option("-T", "--output-type", dest="output_type", help="Audio type used to save detections and/or main stream. If not supplied will: (1). guess from extension or (2). use wav format", type=str, default=None, metavar="STRING")
-        group.add_option("-u", "--use-channel", dest="use_channel", help="Choose channel to use from a multi-channel audio file (requires pydub). 'left', 'right' and 'mix' are accepted values. [Default: 1 (i.e. 1st or left channel)]", type=str, default="1", metavar="STRING")
-        parser.add_option_group(group)
-        
-        
-        group = OptionGroup(parser, "[Tokenization options]", "Set tokenizer options and energy threshold.")
-        group.add_option("-a", "--analysis-window", dest="analysis_window", help="Size of analysis window in seconds [default: %default (10ms)]", type=float, default=0.01, metavar="FLOAT")
-        group.add_option("-n", "--min-duration", dest="min_duration", help="Min duration of a valid audio event in seconds [default: %default]", type=float, default=0.2, metavar="FLOAT")
-        group.add_option("-m", "--max-duration", dest="max_duration", help="Max duration of a valid audio event in seconds [default: %default]", type=float, default=5, metavar="FLOAT")
-        group.add_option("-s", "--max-silence", dest="max_silence", help="Max duration of a consecutive silence within a valid audio event in seconds [default: %default]", type=float, default=0.3, metavar="FLOAT")
-        group.add_option("-d", "--drop-trailing-silence", dest="drop_trailing_silence", help="Drop trailing silence from a detection [default: keep trailing silence]",  action="store_true", default=False)
-        group.add_option("-e", "--energy-threshold", dest="energy_threshold", help="Log energy threshold for detection [default: %default]", type=float, default=50, metavar="FLOAT")
-        parser.add_option_group(group)
-        
-        
-        group = OptionGroup(parser, "[Audio parameters]", "Define audio parameters if data is read from a headerless file (raw or stdin) or you want to use different microphone parameters.")        
-        group.add_option("-r", "--rate", dest="sampling_rate", help="Sampling rate of audio data [default: %default]", type=int, default=16000, metavar="INT")
-        group.add_option("-c", "--channels", dest="channels", help="Number of channels of audio data [default: %default]", type=int, default=1, metavar="INT")
-        group.add_option("-w", "--width", dest="sample_width", help="Number of bytes per audio sample [default: %default]", type=int, default=2, metavar="INT")
-        parser.add_option_group(group)
-        
-        group = OptionGroup(parser, "[Do something with detections]", "Use these options to print, play or plot detections.") 
-        group.add_option("-C", "--command", dest="command", help="Command to call when an audio detection occurs. Use $ to represent the file name to use with the command (e.g. -C 'du -h $')", default=None, type=str, metavar="STRING")
-        group.add_option("-E", "--echo", dest="echo", help="Play back each detection immediately using pyaudio [default: do not play]",  action="store_true", default=False)
-        group.add_option("-p", "--plot", dest="plot", help="Plot and show audio signal and detections (requires matplotlib)",  action="store_true", default=False)
-        group.add_option("", "--save-image", dest="save_image", help="Save plotted audio signal and detections as a picture or a PDF file (requires matplotlib)",  type=str, default=None, metavar="FILE")
-        group.add_option("", "--printf", dest="printf", help="print detections one per line using a user supplied format (e.g. '[{id}]: {start} -- {end}'). Available keywords {id}, {start} and {end}",  type=str, default="{id} {start} {end}", metavar="STRING")
-        group.add_option("", "--time-format", dest="time_format", help="format used to print {start} and {end}. [Default= %default]. %S: absolute time in sec. %I: absolute time in ms. If at least one of (%h, %m, %s, %i) is used, convert time into hours, minutes, seconds and millis (e.g. %h:%m:%s.%i). Only required fields are printed",  type=str, default="%S", metavar="STRING")
-        parser.add_option_group(group)
-        
-        parser.add_option("-q", "--quiet", dest="quiet", help="Do not print any information about detections [default: print 'id', 'start' and 'end' of each detection]",  action="store_true", default=False)
-        parser.add_option("-D", "--debug", dest="debug", help="Print processing operations to STDOUT",  action="store_true", default=False)
-        parser.add_option("", "--debug-file", dest="debug_file", help="Print processing operations to FILE",  type=str, default=None, metavar="FILE")
-        
-        
+        parser = ArgumentParser(
+            prog=program_name, description="An Audio Tokenization tool"
+        )
+        parser.add_argument(
+            "--version", "-v", action="version", version=__version__
+        )
+        group = parser.add_argument_group("Input-Output options")
+        group.add_argument(
+            dest="input",
+            help="Input audio or video file. Use '-' for stdin "
+            "[default: read from microphone using pyaudio]",
+            metavar="input",
+            nargs="?",
+            default=None,
+        )
+        group.add_argument(
+            "-I",
+            "--input-device-index",
+            dest="input_device_index",
+            help="Audio device index [default: %(default)s]. "
+            "Optional and only effective when using PyAudio",
+            type=int,
+            default=None,
+            metavar="INT",
+        )
+        group.add_argument(
+            "-F",
+            "--audio-frame-per-buffer",
+            dest="frame_per_buffer",
+            help="Audio frame per buffer [default: %(default)s]. "
+            "Optional and only effective when using PyAudio",
+            type=int,
+            default=1024,
+            metavar="INT",
+        )
+        group.add_argument(
+            "-f",
+            "--input-format",
+            dest="input_format",
+            type=str,
+            default=None,
+            help="Input audio file format. If not given, guess format from "
+            "extension. If output file name has no extension, guess format "
+            "from file header (requires pydub). If none of the previous is "
+            "true, raise an error",
+            metavar="STRING",
+        )
+        group.add_argument(
+            "-M",
+            "--max-read",
+            dest="max_read",
+            type=float,
+            default=None,
+            help="Maximum data (in seconds) to read from microphone or file "
+            "[default: read until the end of file/stream]",
+            metavar="FLOAT",
+        )
+        group.add_argument(
+            "-L",
+            "--large-file",
+            dest="large_file",
+            action="store_true",
+            default=False,
+            help="Whether input file should be treated as a large file. "
+            "If True, data will be read from file on demand, otherwise all "
+            "audio data is loaded to memory before tokenization.",
+        )
+        group.add_argument(
+            "-O",
+            "--save-stream",
+            dest="save_stream",
+            type=str,
+            default=None,
+            help="Save acquired audio data (from file or microphone) to disk."
+            " If omitted no data will be saved. [default: omitted]",
+            metavar="FILE",
+        )
+        group.add_argument(
+            "-o",
+            "--save-detections-as",
+            dest="save_detections_as",
+            type=str,
+            default=None,
+            help="File name format for detections."
+            "The following placeholders can be used to build output file name "
+            "for each detection: {id} (sequential, starts from 1), {start}, "
+            "{end} and {duration}. Time placeholders are in seconds. "
+            "Example: 'Event_{id}_{start}-{end}_{duration:.3f}.wav'",
+            metavar="STRING",
+        )
+        group.add_argument(
+            "-T",
+            "--output-format",
+            dest="output_format",
+            type=str,
+            default=None,
+            help="Audio format used to save detections and/or main stream. "
+            "If not supplied, then it will: (1. be guessed from extension or "
+            "(2. use raw format",
+            metavar="STRING",
+        )
+        group.add_argument(
+            "-u",
+            "--use-channel",
+            dest="use_channel",
+            type=str,
+            default=None,
+            help="Which channel to use for tokenization when input stream is "
+            "multi-channel (0 is the first channel). Default is None, meaning "
+            "that all channels will be considered for tokenization (i.e., get "
+            "any valid audio event regardless of the channel it occurs in). "
+            "This value can also be 'mix' (alias 'avg' or 'average') and "
+            "means mix down all audio channels into one channel (i.e. compute "
+            "average channel) and use the resulting channel for tokenization. "
+            "Whatever option is used, saved audio events will contain the same"
+            " number of channels as input stream. "
+            "[Default: None, use all channels]",
+            metavar="INT/STRING",
+        )
+
+        group = parser.add_argument_group(
+            "Tokenization options", "Set tokenizer options."
+        )
+        group.add_argument(
+            "-a",
+            "--analysis-window",
+            dest="analysis_window",
+            default=0.01,
+            type=float,
+            help="Size of analysis window in seconds [default: %(default)s "
+            "(10ms)]",
+            metavar="FLOAT",
+        )
+        group.add_argument(
+            "-n",
+            "--min-duration",
+            dest="min_duration",
+            type=float,
+            default=0.2,
+            help="Min duration of a valid audio event in seconds "
+            "[default: %(default)s]",
+            metavar="FLOAT",
+        )
+        group.add_argument(
+            "-m",
+            "--max-duration",
+            dest="max_duration",
+            type=float,
+            default=5,
+            help="Max duration of a valid audio event in seconds "
+            "[default: %(default)s]",
+            metavar="FLOAT",
+        )
+        group.add_argument(
+            "-s",
+            "--max-silence",
+            dest="max_silence",
+            type=float,
+            default=0.3,
+            help="Max duration of a consecutive silence within a valid audio "
+            "event in seconds [default: %(default)s]",
+            metavar="FLOAT",
+        )
+        group.add_argument(
+            "-d",
+            "--drop-trailing-silence",
+            dest="drop_trailing_silence",
+            action="store_true",
+            default=False,
+            help="Drop trailing silence from a detection [default: keep "
+            "trailing silence]",
+        )
+        group.add_argument(
+            "-R",
+            "--strict-min-duration",
+            dest="strict_min_duration",
+            action="store_true",
+            default=False,
+            help="Reject an event shorter than --min-duration even if it's "
+            "adjacent to the latest valid event that reached max-duration "
+            "[default: keep such events]",
+        )
+        group.add_argument(
+            "-e",
+            "--energy-threshold",
+            dest="energy_threshold",
+            type=float,
+            default=50,
+            help="Log energy threshold for detection [default: %(default)s]",
+            metavar="FLOAT",
+        )
+
+        group = parser.add_argument_group(
+            "Audio parameters",
+            "Define audio parameters if data is read from a "
+            "headerless file (raw or stdin) or you want to use "
+            "different microphone parameters.",
+        )
+        group.add_argument(
+            "-r",
+            "--rate",
+            dest="sampling_rate",
+            type=int,
+            default=16000,
+            help="Sampling rate of audio data [default: %(default)s]",
+            metavar="INT",
+        )
+        group.add_argument(
+            "-c",
+            "--channels",
+            dest="channels",
+            type=int,
+            default=1,
+            help="Number of channels of audio data [default: %(default)s]",
+            metavar="INT",
+        )
+        group.add_argument(
+            "-w",
+            "--width",
+            dest="sample_width",
+            type=int,
+            default=2,
+            help="Number of bytes per audio sample [default: %(default)s]",
+            metavar="INT",
+        )
+
+        group = parser.add_argument_group(
+            "Do something with audio events",
+            "Use these options to print, play back or plot detections.",
+        )
+        group.add_argument(
+            "-C",
+            "--command",
+            dest="command",
+            type=str,
+            help="Command to call when an audio detection occurs. Use '{file}' "
+            "as a placeholder for the temporary wav file that will contain "
+            "event's data (e.g., \"-C 'du -h {file}'\" to print out file size "
+            " or \"-C 'play -q {file}'\" to play audio with sox)",
+            metavar="STRING",
+        )
+        group.add_argument(
+            "-E",
+            "--echo",
+            dest="echo",
+            action="store_true",
+            default=False,
+            help="Play back each detection immediately using pyaudio",
+        )
+        group.add_argument(
+            "-B",
+            "--progress-bar",
+            dest="progress_bar",
+            action="store_true",
+            default=False,
+            help="Show a progress bar when playing audio",
+        )
+        group.add_argument(
+            "-p",
+            "--plot",
+            dest="plot",
+            action="store_true",
+            default=False,
+            help="Plot and show audio signal and detections (requires "
+            "matplotlib)",
+        )
+        group.add_argument(
+            "--save-image",
+            dest="save_image",
+            type=str,
+            help="Save plotted audio signal and detections as a picture or a "
+            "PDF file (requires matplotlib)",
+            metavar="FILE",
+        )
+        group.add_argument(
+            "--printf",
+            dest="printf",
+            type=str,
+            default="{id} {start} {end}",
+            help="Print audio events information, one per line, using this "
+            "format. Format can contain text with the following placeholders: "
+            "{id} (sequential, starts from 1), {start}, {end}, {duration} and "
+            "{timestamp}. The first 3 time placeholders are in seconds and "
+            "their format can be set using --time-format argument. "
+            "{timestamp} is the system timestamp (date and time) of the event "
+            "and can be set using --timestamp-format argument.\n"
+            "Example: '[{id}]: {start} -> {end} -- {timestamp}'",
+            metavar="STRING",
+        )
+        group.add_argument(
+            "--time-format",
+            dest="time_format",
+            type=str,
+            default="%S",
+            help="Format used to print {start}, {end} and {duration} "
+            "placeholders used with --printf [default= %(default)s]. The "
+            "following formats are accepted:\n"
+            "%%S: absolute time in seconds. %%I: absolute time in ms. If at "
+            "least one of (%%h, %%m, %%s, %%i) is used, convert time into "
+            "hours, minutes, seconds and millis (e.g. %%h:%%m:%%s.%%i). Only "
+            "supplied fields are printed. Note that %%S and %%I can only be "
+            "used alone",
+            metavar="STRING",
+        )
+        group.add_argument(
+            "--timestamp-format",
+            dest="timestamp_format",
+            type=str,
+            default="%Y/%m/%d %H:%M:%S",
+            help="Format used to print {timestamp}. Should be a format "
+            "accepted by 'datetime' standard module. Default: "
+            "'%%Y/%%m/%%d %%H:%%M:%%S'",
+        )
+        parser.add_argument(
+            "-q",
+            "--quiet",
+            dest="quiet",
+            action="store_true",
+            default=False,
+            help="Do not print any information about detections [default: "
+            "print 'id', 'start' and 'end' of each detection]",
+        )
+        parser.add_argument(
+            "-D",
+            "--debug",
+            dest="debug",
+            action="store_true",
+            default=False,
+            help="Print processing operations to STDOUT",
+        )
+        parser.add_argument(
+            "--debug-file",
+            dest="debug_file",
+            type=str,
+            default=None,
+            help="Print processing operations to FILE",
+            metavar="FILE",
+        )
+
+        args = parser.parse_args(argv)
+        logger = make_logger(args.debug, args.debug_file)
+        kwargs = make_kwargs(args)
+        reader, observers = initialize_workers(
+            logger=logger, **kwargs.io, **kwargs.miscellaneous
+        )
+        tokenizer_worker = workers.TokenizerWorker(
+            reader, observers, logger=logger, **kwargs.split
+        )
+        tokenizer_worker.start_all()
 
-        # process options
-        (opts, args) = parser.parse_args(argv)
-        
-        if opts.input == "-":
-            asource = StdinAudioSource(sampling_rate = opts.sampling_rate,
-                                       sample_width = opts.sample_width,
-                                       channels = opts.channels)
-        #read data from a file
-        elif opts.input is not None:
-            asource = file_to_audio_source(filename=opts.input, filetype=opts.input_type, uc=opts.use_channel)
-        
-        # read data from microphone via pyaudio
-        else:
-            try:
-                asource = PyAudioSource(sampling_rate = opts.sampling_rate,
-                                        sample_width = opts.sample_width,
-                                        channels = opts.channels)
-            except Exception:
-                sys.stderr.write("Cannot read data from audio device!\n")
-                sys.stderr.write("You should either install pyaudio or read data from STDIN\n")
-                sys.exit(2)
-               
-        logger = logging.getLogger(LOGGER_NAME)
-        logger.setLevel(logging.DEBUG)
-        
-        handler = logging.StreamHandler(sys.stdout)
-        if opts.quiet or not opts.debug:
-            # only critical messages will be printed
-            handler.setLevel(logging.CRITICAL)
-        else:
-            handler.setLevel(logging.DEBUG)
-        
-        logger.addHandler(handler)
-        
-        if opts.debug_file is not None:
-            logger.setLevel(logging.DEBUG)
-            opts.debug = True
-            handler = logging.FileHandler(opts.debug_file, "w")
-            fmt = logging.Formatter('[%(asctime)s] | %(message)s')
-            handler.setFormatter(fmt)
-            handler.setLevel(logging.DEBUG)
-            logger.addHandler(handler)
-        
-        record = opts.output_main is not None or opts.plot or opts.save_image is not None
-                        
-        ads = ADSFactory.ads(audio_source = asource, block_dur = opts.analysis_window, max_time = opts.max_time, record = record)
-        validator = AudioEnergyValidator(sample_width=asource.get_sample_width(), energy_threshold=opts.energy_threshold)
-        
-        
-        if opts.drop_trailing_silence:
-            mode = StreamTokenizer.DROP_TRAILING_SILENCE
-        else:
-            mode = 0
-        
-        analysis_window_per_second = 1. / opts.analysis_window
-        tokenizer = StreamTokenizer(validator=validator, min_length=opts.min_duration * analysis_window_per_second,
-                                    max_length=int(opts.max_duration * analysis_window_per_second),
-                                    max_continuous_silence=opts.max_silence * analysis_window_per_second,
-                                    mode = mode)
-        
-        
-        observers = []
-        tokenizer_worker = None
-        
-        if opts.output_tokens is not None:
-            
-            try:
-                # check user format is correct
-                fname  = opts.output_tokens.format(N=0, start=0, end=0)
-                
-                # find file type for detections
-                tok_type =  opts.output_type
-                if tok_type is None:
-                    tok_type = os.path.splitext(opts.output_tokens)[1][1:]
-                if tok_type == "": 
-                    tok_type = "wav"
-                
-                token_saver = TokenSaverWorker(name_format=opts.output_tokens, filetype=tok_type,
-                                               debug=opts.debug, logger=logger, sr=asource.get_sampling_rate(),
-                                               sw=asource.get_sample_width(),
-                                               ch=asource.get_channels())
-                observers.append(token_saver)
-            
-            except Exception:
-                sys.stderr.write("Wrong format for detections file name: '{0}'\n".format(opts.output_tokens))
-                sys.exit(2)
-            
-        if opts.echo:
-            try:
-                player = player_for(asource)
-                player_worker = PlayerWorker(player=player, debug=opts.debug, logger=logger)
-                observers.append(player_worker)
-            except Exception:
-                sys.stderr.write("Cannot get an audio player!\n")
-                sys.stderr.write("You should either install pyaudio or supply a command (-C option) to play audio\n")
-                sys.exit(2)
-                
-        if opts.command is not None and len(opts.command) > 0:
-            cmd_worker = CommandLineWorker(command=opts.command, debug=opts.debug, logger=logger)
-            observers.append(cmd_worker)
-        
-        if not opts.quiet or opts.plot is not None or opts.save_image is not None:    
-            oformat = opts.printf.replace("\\n", "\n").replace("\\t", "\t").replace("\\r", "\r")
-            converter = seconds_to_str_fromatter(opts.time_format)
-            log_worker = LogWorker(print_detections = not opts.quiet, output_format=oformat,
-                                   time_formatter=converter, logger=logger, debug=opts.debug)
-            observers.append(log_worker)
-        
-        tokenizer_worker = TokenizerWorker(ads, tokenizer, opts.analysis_window, observers)
-        
-        def _save_main_stream():
-            # find file type
-            main_type =  opts.output_type
-            if main_type is None:
-                main_type = os.path.splitext(opts.output_main)[1][1:]
-            if main_type == "": 
-                main_type = "wav"
-            ads.close()
-            ads.rewind()
-            data = ads.get_audio_source().get_data_buffer()
-            if len(data) > 0:
-                save_audio_data(data=data, filename=opts.output_main, filetype=main_type, sr=asource.get_sampling_rate(),
-                                sw = asource.get_sample_width(),
-                                ch = asource.get_channels())
-        
-        def _plot():
-            import numpy as np
-            ads.close()
-            ads.rewind()
-            data = ads.get_audio_source().get_data_buffer()
-            signal = AudioEnergyValidator._convert(data, asource.get_sample_width())
-            detections = [(det[3] , det[4]) for det in log_worker.detections]
-            max_amplitude = 2**(asource.get_sample_width() * 8 - 1) - 1
-            energy_as_amp = np.sqrt(np.exp(opts.energy_threshold * np.log(10) / 10)) / max_amplitude
-            plot_all(signal / max_amplitude, asource.get_sampling_rate(), energy_as_amp, detections, show = opts.plot, save_as = opts.save_image)
-        
-        
-        # start observer threads
-        for obs in observers:
-            obs.start()
-        # start tokenization thread
-        tokenizer_worker.start()
-        
         while True:
             time.sleep(1)
             if len(threading.enumerate()) == 1:
-                break
-            
-        tokenizer_worker = None
-            
-        if opts.output_main is not None:
-            _save_main_stream()
-        if opts.plot or opts.save_image is not None:
-            _plot()
-            
-        return 0
-            
-    except KeyboardInterrupt:
-        
+                raise EndOfProcessing
+
+    except (KeyboardInterrupt, EndOfProcessing):
         if tokenizer_worker is not None:
-            tokenizer_worker.stop()
-        for obs in observers:
-            obs.stop()
-            
-        if opts.output_main is not None:
-            _save_main_stream()
-        if opts.plot or opts.save_image is not None:
-            _plot()
-        
+            tokenizer_worker.stop_all()
+
+            if isinstance(reader, workers.StreamSaverWorker):
+                reader.join()
+                try:
+                    reader.save_stream()
+                except AudioEncodingWarning as ae_warn:
+                    print(str(ae_warn), file=sys.stderr)
+
+            if args.plot or args.save_image is not None:
+                from .plotting import plot
+
+                reader.rewind()
+                record = AudioRegion(
+                    reader.data, reader.sr, reader.sw, reader.ch
+                )
+                detections = (
+                    (det.start, det.end) for det in tokenizer_worker.detections
+                )
+                plot(
+                    record,
+                    detections=detections,
+                    energy_threshold=args.energy_threshold,
+                    show=True,
+                    save_as=args.save_image,
+                )
         return 0
 
-    except Exception as e:
-        sys.stderr.write(program_name + ": " + str(e) + "\n")
-        sys.stderr.write("for help use -h\n")
-        
-        return 2
 
 if __name__ == "__main__":
-    if DEBUG:
-        sys.argv.append("-h")
-    if TESTRUN:
-        import doctest
-        doctest.testmod()
-    if PROFILE:
-        import cProfile
-        import pstats
-        profile_filename = 'auditok.auditok_profile.txt'
-        cProfile.run('main()', profile_filename)
-        statsfile = open("profile_stats.txt", "wb")
-        p = pstats.Stats(profile_filename, stream=statsfile)
-        stats = p.strip_dirs().sort_stats('cumulative')
-        stats.print_stats()
-        statsfile.close()
-        sys.exit(0)
-    sys.exit(main())
+    sys.exit(main(None))
diff --git a/libs/auditok/cmdline_util.py b/libs/auditok/cmdline_util.py
new file mode 100755
index 000000000..bde72aa36
--- /dev/null
+++ b/libs/auditok/cmdline_util.py
@@ -0,0 +1,126 @@
+import sys
+import logging
+from collections import namedtuple
+from . import workers
+from .util import AudioDataSource
+from .io import player_for
+
+_AUDITOK_LOGGER = "AUDITOK_LOGGER"
+KeywordArguments = namedtuple(
+    "KeywordArguments", ["io", "split", "miscellaneous"]
+)
+
+
+def make_kwargs(args_ns):
+    if args_ns.save_stream is None:
+        record = args_ns.plot or (args_ns.save_image is not None)
+    else:
+        record = False
+    try:
+        use_channel = int(args_ns.use_channel)
+    except (ValueError, TypeError):
+        use_channel = args_ns.use_channel
+
+    io_kwargs = {
+        "input": args_ns.input,
+        "audio_format": args_ns.input_format,
+        "max_read": args_ns.max_read,
+        "block_dur": args_ns.analysis_window,
+        "sampling_rate": args_ns.sampling_rate,
+        "sample_width": args_ns.sample_width,
+        "channels": args_ns.channels,
+        "use_channel": use_channel,
+        "save_stream": args_ns.save_stream,
+        "save_detections_as": args_ns.save_detections_as,
+        "export_format": args_ns.output_format,
+        "large_file": args_ns.large_file,
+        "frames_per_buffer": args_ns.frame_per_buffer,
+        "input_device_index": args_ns.input_device_index,
+        "record": record,
+    }
+
+    split_kwargs = {
+        "min_dur": args_ns.min_duration,
+        "max_dur": args_ns.max_duration,
+        "max_silence": args_ns.max_silence,
+        "drop_trailing_silence": args_ns.drop_trailing_silence,
+        "strict_min_dur": args_ns.strict_min_duration,
+        "energy_threshold": args_ns.energy_threshold,
+    }
+
+    miscellaneous = {
+        "echo": args_ns.echo,
+        "progress_bar": args_ns.progress_bar,
+        "command": args_ns.command,
+        "quiet": args_ns.quiet,
+        "printf": args_ns.printf,
+        "time_format": args_ns.time_format,
+        "timestamp_format": args_ns.timestamp_format,
+    }
+    return KeywordArguments(io_kwargs, split_kwargs, miscellaneous)
+
+
+def make_logger(stderr=False, file=None, name=_AUDITOK_LOGGER):
+    if not stderr and file is None:
+        return None
+    logger = logging.getLogger(name)
+    logger.setLevel(logging.INFO)
+    if stderr:
+        handler = logging.StreamHandler(sys.stderr)
+        handler.setLevel(logging.INFO)
+        logger.addHandler(handler)
+
+    if file is not None:
+        handler = logging.FileHandler(file, "w")
+        fmt = logging.Formatter("[%(asctime)s] | %(message)s")
+        handler.setFormatter(fmt)
+        handler.setLevel(logging.INFO)
+        logger.addHandler(handler)
+    return logger
+
+
+def initialize_workers(logger=None, **kwargs):
+    observers = []
+    reader = AudioDataSource(source=kwargs["input"], **kwargs)
+    if kwargs["save_stream"] is not None:
+        reader = workers.StreamSaverWorker(
+            reader,
+            filename=kwargs["save_stream"],
+            export_format=kwargs["export_format"],
+        )
+        reader.start()
+
+    if kwargs["save_detections_as"] is not None:
+        worker = workers.RegionSaverWorker(
+            kwargs["save_detections_as"],
+            kwargs["export_format"],
+            logger=logger,
+        )
+        observers.append(worker)
+
+    if kwargs["echo"]:
+        player = player_for(reader)
+        worker = workers.PlayerWorker(
+            player, progress_bar=kwargs["progress_bar"], logger=logger
+        )
+        observers.append(worker)
+
+    if kwargs["command"] is not None:
+        worker = workers.CommandLineWorker(
+            command=kwargs["command"], logger=logger
+        )
+        observers.append(worker)
+
+    if not kwargs["quiet"]:
+        print_format = (
+            kwargs["printf"]
+            .replace("\\n", "\n")
+            .replace("\\t", "\t")
+            .replace("\\r", "\r")
+        )
+        worker = workers.PrintWorker(
+            print_format, kwargs["time_format"], kwargs["timestamp_format"]
+        )
+        observers.append(worker)
+
+    return reader, observers
diff --git a/libs/auditok/core.py b/libs/auditok/core.py
index 47441d2b7..af00dc7af 100644
--- a/libs/auditok/core.py
+++ b/libs/auditok/core.py
@@ -1,264 +1,1267 @@
 """
-This module gathers processing (i.e. tokenization) classes.
-
-Class summary
-=============
-
 .. autosummary::
+    :toctree: generated/
 
-        StreamTokenizer
+    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.
 
-from auditok.util import DataValidator
+        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.
 
-__all__ = ["StreamTokenizer"]
+        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.
 
-class StreamTokenizer():
+
+        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` :
-            instance of `DataValidator` that implements `is_valid` method.
-        
-        `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, default=0)*
-            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, default=0)*
-            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, default=0)*
-            `mode` can be:
-        
-        1. `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` (given that the above conditions
-        are fulfilled of course).
-           
-        :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:
-            
-        .. code:: python
-        
-            from auditok import StreamTokenizer, 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)
-                    
-                    
-        :output:
-    
-         .. code:: python
-         
-            [(['A', 'A', 'A', 'A'], 3, 6), (['B', 'B'], 7, 8)]
-
-
-        The following tokenizer will however reject the 'BB' token:
-     
-        .. code:: python
-                
-            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)
-        
-        :output:
-            
-        .. code:: python
-            
-            [(['A', 'A', 'A', 'A'], 3, 6)]
-            
-           
-        2. `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:
-           
-        - a. `max_continuous_silence` is reached
-           
-        :or:
-           
-        - b. Its length reaches `max_length`. This is called 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 tailing silence can be removed if you use
-        the `StreamTokenizer.DROP_TRAILING_SILENCE` mode.
-    
-        :Example:
-    
-        .. code:: python
-                       
-             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)
-        
-        :output:
-            
-        .. code:: python
-                
-            [(['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)]
-    
-        
-        
-        3. `StreamTokenizer.STRICT_MIN_LENGTH | StreamTokenizer.DROP_TRAILING_SILENCE`:
-        use both options. That means: first remove tailing silence, then ckeck if the
-        token still has at least a length of `min_length`.
+
+    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 
+    POSSIBLE_NOISE = 2
     NOISE = 3
-    
+    NORMAL = 0
     STRICT_MIN_LENGTH = 2
     DROP_TRAILING_SILENCE = 4
-    # alias
-    DROP_TAILING_SILENCE = 4
-    
-    def __init__(self, validator, 
-                 min_length, max_length, max_continuous_silence,
-                 init_min=0, init_max_silence=0,
-                 mode=0):
-        
-        if not isinstance(validator, DataValidator):
-            raise TypeError("'validator' must be an instance of 'DataValidator'")
-        
+
+    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))
-        
+            raise ValueError(
+                "'max_length' must be > 0 (value={0})".format(max_length)
+            )
+
         if min_length <= 0 or min_length > max_length:
-            raise ValueError("'min_length' must be > 0 and <= 'max_length' (value={0})".format(min_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:
-            raise ValueError("'max_continuous_silence' must be < 'max_length' (value={0})".format(max_continuous_silence))
-        
+            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))
-            
+            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._mode = None
-        self.set_mode(mode)
-        self._strict_min_length = (mode & self.STRICT_MIN_LENGTH) != 0
-        self._drop_tailing_silence  = (mode & self.DROP_TRAILING_SILENCE) != 0
-        
+        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):
-        """
-        :Parameters:
-        
-            `mode` : *(int)*
-                New mode, must be one of:
-                    
-                
-            - `StreamTokenizer.STRICT_MIN_LENGTH`
-            
-            - `StreamTokenizer.DROP_TRAILING_SILENCE`
-            
-            - `StreamTokenizer.STRICT_MIN_LENGTH | StreamTokenizer.DROP_TRAILING_SILENCE`
-                   
-            - `0`
-                       
-        See `StreamTokenizer.__init__` for more information about the mode.
-        """
-        
-        if not mode in [self.STRICT_MIN_LENGTH, self.DROP_TRAILING_SILENCE,
-           self.STRICT_MIN_LENGTH | self.DROP_TRAILING_SILENCE, 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_tailing_silence  = (mode & self.DROP_TRAILING_SILENCE) != 0
-        
-    
-    def get_mode(self):
-        """
-        Return the current mode. To check whether a specific mode is activated use
-        the bitwise 'and' operator `&`. Example:
-           
-        .. code:: python 
-                
-            if mode & self.STRICT_MIN_LENGTH != 0:
-               do_something()
-        """
-        return self._mode
-        
+        self._drop_trailing_silence = (mode & self.DROP_TRAILING_SILENCE) != 0
+
     def _reinitialize(self):
         self._contiguous_token = False
         self._data = []
@@ -266,112 +1269,114 @@ class StreamTokenizer():
         self._state = self.SILENCE
         self._current_frame = -1
         self._deliver = self._append_token
-    
-    
-    def tokenize(self, data_source, callback=None):
+
+    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.
-        
+        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.
-        
+           `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.
-           
-           
+               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:
-        
+           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. 
-        
+
+           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()
-        
-        if callback is not None:
-            self._deliver = callback
-        
         while True:
-            frame =  data_source.read()
+            frame = data_source.read()
+            self._current_frame += 1
             if frame is None:
+                token = self._post_process()
+                if token is not None:
+                    yield token
                 break
-            self._current_frame += 1
-            self._process(frame)
-            
-        self._post_process()
-        
-        if callback is None:
-            _ret = self._tokens
-            self._tokens = None
-            return _ret
-        
-        
-    def _process(self, frame):
-        
-        frame_is_valid = self.validator.is_valid(frame)
-        
+            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:
+
+                if self._init_count >= self.init_min:
                     self._state = self.NOISE
                     if len(self._data) >= self.max_length:
-                        self._process_end_of_detection(True)
+                        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:
+                if self._init_count >= self.init_min:
                     self._state = self.NOISE
                     if len(self._data) >= self.max_length:
-                        self._process_end_of_detection(True)
-            
-            else:                
+                        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:
+                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:
-                    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._process_end_of_detection()
+                    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
@@ -379,61 +1384,63 @@ class StreamTokenizer():
                 self._data.append(frame)
                 self._state = self.POSSIBLE_SILENCE
                 if len(self._data) == self.max_length:
-                    self._process_end_of_detection(True)
-                    # don't reset _silence_length because we still 
+                    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:
-                    self._process_end_of_detection(True)
-                
+                    return self._process_end_of_detection(True)
+
             else:
                 if self._silence_length >= self.max_continuous_silence:
-                    if self._silence_length < len(self._data):
-                        # _deliver only gathered frames aren't all silent                    
-                        self._process_end_of_detection()
-                    else:
-                        self._data = []
                     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:
-                        self._process_end_of_detection(True)
-                        # don't reset _silence_length because we still 
+                        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:
-                self._process_end_of_detection()
-    
-    
+                return self._process_end_of_detection()
+
     def _process_end_of_detection(self, truncated=False):
-        
-        if not truncated and self._drop_tailing_silence and self._silence_length > 0:
+
+        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):
-            
-            
-            
-            _end_frame = self._start_frame + len(self._data) - 1
-            self._deliver(self._data, self._start_frame, _end_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
@@ -441,12 +1448,11 @@ class StreamTokenizer():
                 self._contiguous_token = True
             else:
                 self._contiguous_token = False
+            return token
         else:
-            self._contiguous_token = False       
-        
+            self._contiguous_token = False
+
         self._data = []
-            
-    
-    
+
     def _append_token(self, data, start, end):
         self._tokens.append((data, start, end))
diff --git a/libs/auditok/dataset.py b/libs/auditok/dataset.py
index 1a3a7af5c..98dc5d1d4 100644
--- a/libs/auditok/dataset.py
+++ b/libs/auditok/dataset.py
@@ -1,19 +1,31 @@
 """
-This module contains links to audio files you can use for test purposes.
+This module contains links to audio files that can be used for test purposes.
+
+.. autosummary::
+    :toctree: generated/
+
+    one_to_six_arabic_16000_mono_bc_noise
+    was_der_mensch_saet_mono_44100_lead_trail_silence
 """
 
 import os
 
-__all__ = ["one_to_six_arabic_16000_mono_bc_noise", "was_der_mensch_saet_mono_44100_lead_trail_silence"]
+__all__ = [
+    "one_to_six_arabic_16000_mono_bc_noise",
+    "was_der_mensch_saet_mono_44100_lead_trail_silence",
+]
 
 _current_dir = os.path.dirname(os.path.realpath(__file__))
 
 one_to_six_arabic_16000_mono_bc_noise = "{cd}{sep}data{sep}1to6arabic_\
-16000_mono_bc_noise.wav".format(cd=_current_dir, sep=os.path.sep)
+16000_mono_bc_noise.wav".format(
+    cd=_current_dir, sep=os.path.sep
+)
 """A wave file that contains a pronunciation of Arabic numbers from 1 to 6"""
 
-
 was_der_mensch_saet_mono_44100_lead_trail_silence = "{cd}{sep}data{sep}was_\
 der_mensch_saet_das_wird_er_vielfach_ernten_44100Hz_mono_lead_trail_\
-silence.wav".format(cd=_current_dir, sep=os.path.sep)
-""" A wave file that contains a sentence between long leading and trailing periods of silence"""
\ No newline at end of file
+silence.wav".format(
+    cd=_current_dir, sep=os.path.sep
+)
+"""A wave file that contains a sentence with a long leading and trailing silence"""
diff --git a/libs/auditok/exceptions.py b/libs/auditok/exceptions.py
index 0026a9d89..7bc5054ee 100644
--- a/libs/auditok/exceptions.py
+++ b/libs/auditok/exceptions.py
@@ -1,9 +1,41 @@
-"""
-November 2015
-@author: Amine SEHILI <[email protected]>
-"""
-
 class DuplicateArgument(Exception):
     pass
 
 
+class TooSamllBlockDuration(ValueError):
+    """Raised when block_dur results in a block_size smaller than one sample."""
+
+    def __init__(self, message, block_dur, sampling_rate):
+        self.block_dur = block_dur
+        self.sampling_rate = sampling_rate
+        super(TooSamllBlockDuration, self).__init__(message)
+
+
+class TimeFormatError(Exception):
+    """Raised when a duration formatting directive is unknown."""
+
+
+class EndOfProcessing(Exception):
+    """Raised within command line script's main function to jump to
+    postprocessing code."""
+
+
+class AudioIOError(Exception):
+    """Raised when a compressed audio file cannot be loaded or when trying
+    to read from a not yet open AudioSource"""
+
+
+class AudioParameterError(AudioIOError):
+    """Raised when one audio parameter is missing when loading raw data or
+    saving data to a format other than raw. Also raised when an audio
+    parameter has a wrong value."""
+
+
+class AudioEncodingError(Exception):
+    """Raised if audio data can not be encoded in the provided format"""
+
+
+class AudioEncodingWarning(RuntimeWarning):
+    """Raised if audio data can not be encoded in the provided format
+    but saved as wav.
+    """
diff --git a/libs/auditok/io.py b/libs/auditok/io.py
index 665ab274d..b5fb61a76 100644
--- a/libs/auditok/io.py
+++ b/libs/auditok/io.py
@@ -1,499 +1,1021 @@
 """
 Module for low-level audio input-output operations.
 
-Class summary
-=============
-
 .. autosummary::
+    :toctree: generated/
 
-        AudioSource
-        Rewindable
-        BufferAudioSource
-        WaveAudioSource
-        PyAudioSource
-        StdinAudioSource
-        PyAudioPlayer
-        
+    AudioSource
+    Rewindable
+    BufferAudioSource
+    WaveAudioSource
+    PyAudioSource
+    StdinAudioSource
+    PyAudioPlayer
+    from_file
+    to_file
+    player_for
+"""
+import os
+import sys
+import wave
+import warnings
+from abc import ABC, abstractmethod
+from functools import partial
+from .exceptions import AudioIOError, AudioParameterError
 
-Function summary
-================
+try:
+    from pydub import AudioSegment
 
-.. autosummary::
+    _WITH_PYDUB = True
+except ImportError:
+    _WITH_PYDUB = False
 
-        from_file
-        player_for
-"""
+try:
+    from tqdm import tqdm as _tqdm
 
-from abc import ABCMeta, abstractmethod
-import wave
-import sys
+    DEFAULT_BAR_FORMAT_TQDM = "|" + "{bar}" + "|" + "[{elapsed}/{duration}]"
+    DEFAULT_NCOLS_TQDM = 30
+    DEFAULT_NCOLS_TQDM = 30
+    DEFAULT_MIN_INTERVAL_TQDM = 0.05
+    _WITH_TQDM = True
+except ImportError:
+    _WITH_TQDM = False
 
-__all__ = ["AudioSource", "Rewindable", "BufferAudioSource", "WaveAudioSource",
-           "PyAudioSource", "StdinAudioSource", "PyAudioPlayer", "from_file", "player_for"]
 
-DEFAULT_SAMPLE_RATE = 16000
+__all__ = [
+    "AudioSource",
+    "Rewindable",
+    "BufferAudioSource",
+    "RawAudioSource",
+    "WaveAudioSource",
+    "PyAudioSource",
+    "StdinAudioSource",
+    "PyAudioPlayer",
+    "from_file",
+    "to_file",
+    "player_for",
+]
+
+DEFAULT_SAMPLING_RATE = 16000
 DEFAULT_SAMPLE_WIDTH = 2
 DEFAULT_NB_CHANNELS = 1
 
 
-class AudioSource():
-    """ 
+def check_audio_data(data, sample_width, channels):
+    sample_size_bytes = int(sample_width * channels)
+    nb_samples = len(data) // sample_size_bytes
+    if nb_samples * sample_size_bytes != len(data):
+        raise AudioParameterError(
+            "The length of audio data must be an integer "
+            "multiple of `sample_width * channels`"
+        )
+
+
+def _guess_audio_format(fmt, filename):
+    if fmt is None:
+        extension = os.path.splitext(filename.lower())[1][1:]
+        if extension:
+            fmt = extension
+        else:
+            return None
+    fmt = fmt.lower()
+    if fmt == "wave":
+        fmt = "wav"
+    return fmt
+
+
+def _get_audio_parameters(param_dict):
+    """
+    Get audio parameters from a dictionary of parameters. An audio parameter can
+    have a long name or a short name. If the long name is present, the short
+    name will be ignored. If neither is present then `AudioParameterError` is
+    raised.
+
+    Expected parameters are:
+
+        - `sampling_rate`, `sr` : int, sampling rate.
+
+        - `sample_width`, `sw` : int, sample size in bytes.
+
+        - `channels`, `ch` : int, number of channels.
+
+    Returns
+    -------
+    audio_parameters : tuple
+        a tuple for audio parameters as (sampling_rate, sample_width, channels).
+    """
+    err_message = (
+        "'{ln}' (or '{sn}') must be a positive integer, found: '{val}'"
+    )
+    parameters = []
+    for (long_name, short_name) in (
+        ("sampling_rate", "sr"),
+        ("sample_width", "sw"),
+        ("channels", "ch"),
+    ):
+        param = param_dict.get(long_name, param_dict.get(short_name))
+        if param is None or not isinstance(param, int) or param <= 0:
+            raise AudioParameterError(
+                err_message.format(ln=long_name, sn=short_name, val=param)
+            )
+        parameters.append(param)
+    sampling_rate, sample_width, channels = parameters
+    return sampling_rate, sample_width, channels
+
+
+class AudioSource(ABC):
+    """
     Base class for audio source objects.
-        
-    Subclasses should implement methods to open/close and audio stream 
+
+    Subclasses should implement methods to open/close and audio stream
     and read the desired amount of audio samples.
-    
-    :Parameters:
-        
-        `sampling_rate` : int
-            Number of samples per second of audio stream. Default = 16000.
-        
-        `sample_width` : int
-            Size in bytes of one audio sample. Possible values : 1, 2, 4.
-            Default = 2.
-            
-        `channels` : int
-            Number of channels of audio stream. The current version supports
-            only mono audio streams (i.e. one channel).
-    """
-    
-    __metaclass__ = ABCMeta
-
-    def __init__(self, sampling_rate = DEFAULT_SAMPLE_RATE,
-                 sample_width = DEFAULT_SAMPLE_WIDTH,
-                 channels = DEFAULT_NB_CHANNELS):
-  
-        if not sample_width in (1, 2, 4):
-            raise ValueError("Sample width must be one of: 1, 2 or 4 (bytes)")
-        
-        if channels != 1:
-            raise ValueError("Only mono audio is currently handled")
-            
-        self.sampling_rate = sampling_rate
-        self.sample_width = sample_width
-        self.channels = channels
-      
+
+    Parameters
+    ----------
+    sampling_rate : int
+        number of samples per second of audio data.
+    sample_width : int
+        size in bytes of one audio sample. Possible values: 1, 2 or 4.
+    channels : int
+        number of channels of audio data.
+    """
+
+    def __init__(
+        self, sampling_rate, sample_width, channels,
+    ):
+
+        if sample_width not in (1, 2, 4):
+            raise AudioParameterError(
+                "Sample width must be one of: 1, 2 or 4 (bytes)"
+            )
+
+        self._sampling_rate = sampling_rate
+        self._sample_width = sample_width
+        self._channels = channels
+
     @abstractmethod
     def is_open(self):
-        """ Return True if audio source is open, False otherwise """
-    
+        """Return True if audio source is open, False otherwise."""
+
     @abstractmethod
     def open(self):
-        """ Open audio source """
-    
+        """Open audio source."""
+
     @abstractmethod
     def close(self):
-        """ Close audio source """
-    
+        """Close audio source."""
+
     @abstractmethod
     def read(self, size):
         """
         Read and return `size` audio samples at most.
-        
-        :Parameters:
-        
-            `size` : int
-                the number of samples to read.
-            
-        :Returns:
-            
-            Audio data as a string of length 'N' * 'smaple_width' * 'channels', where 'N' is:
-            
-            - `size` if `size` < 'left_samples'
-            
-            - 'left_samples' if `size` > 'left_samples' 
-        
-        """ 
-    
-    def get_sampling_rate(self):
-        """ Return the number of samples per second of audio stream """
-        return self.sampling_rate
-    
-    def get_sample_width(self):
-        """ Return the number of bytes used to represent one audio sample """
-        return self.sample_width
-    
-    def get_channels(self):
-        """ Return the number of channels of this audio source """
+
+        Parameters
+        -----------
+        size : int
+            Number of samples to read.
+
+        Returns
+        -------
+        data : bytes
+            Audio data as a bytes object of length `N * sample_width * channels`
+            where `N` equals:
+
+            - `size` if `size` <= remaining samples
+
+            - remaining samples if `size` > remaining samples
+        """
+
+    @property
+    def sampling_rate(self):
+        """Number of samples per second of audio stream."""
+        return self._sampling_rate
+
+    @property
+    def sr(self):
+        """Number of samples per second of audio stream (alias for
+        `sampling_rate)`."""
+        return self._sampling_rate
+
+    @property
+    def sample_width(self):
+        """Number of bytes used to represent one audio sample."""
+        return self._sample_width
+
+    @property
+    def sw(self):
+        """Number of bytes used to represent one audio sample (alias for
+        `sample_width`)."""
+        return self._sample_width
+
+    @property
+    def channels(self):
+        """Number of channels in audio stream."""
+        return self._channels
+
+    @property
+    def ch(self):
+        """Number of channels in audio stream (alias for `channels`)."""
         return self.channels
-    
 
 
-class Rewindable():
+class Rewindable(AudioSource):
     """
     Base class for rewindable audio streams.
-    Subclasses should implement methods to return to the beginning of an
-    audio stream as well as method to move to an absolute audio position
-    expressed in time or in number of samples. 
+
+    Subclasses should implement a method to return back to the start of an the
+    stream (`rewind`), as well as a property getter/setter named `position` that
+    reads/sets stream position expressed in number of samples.
     """
-    
-    __metaclass__ = ABCMeta
-    
+
     @abstractmethod
     def rewind(self):
-        """ Go back to the beginning of audio stream """
-        pass
-    
-    @abstractmethod
-    def get_position(self):
-        """ Return the total number of already read samples """
-    
-    @abstractmethod
-    def get_time_position(self):
-        """ Return the total duration in seconds of already read data """
-    
+        """Go back to the beginning of audio stream."""
+
+    @property
     @abstractmethod
-    def set_position(self, position):
-        """ Move to an absolute position 
-        
-        :Parameters:
-        
-            `position` : int
-                number of samples to skip from the start of the stream
-        """
-    
+    def position(self):
+        """Return stream position in number of samples."""
+
+    @position.setter
     @abstractmethod
-    def set_time_position(self, time_position):
-        """ Move to an absolute position expressed in seconds
-        
-        :Parameters:
-        
-            `time_position` : float
-                seconds to skip from the start of the stream
-        """
-        pass
+    def position(self, position):
+        """Set stream position in number of samples."""
+
+    @property
+    def position_s(self):
+        """Return stream position in seconds."""
+        return self.position / self.sampling_rate
 
-    
+    @position_s.setter
+    def position_s(self, position_s):
+        """Set stream position in seconds."""
+        self.position = int(self.sampling_rate * position_s)
 
-class BufferAudioSource(AudioSource, Rewindable):
+    @property
+    def position_ms(self):
+        """Return stream position in milliseconds."""
+        return (self.position * 1000) // self.sampling_rate
+
+    @position_ms.setter
+    def position_ms(self, position_ms):
+        """Set stream position in milliseconds."""
+        if not isinstance(position_ms, int):
+            raise ValueError("position_ms should be an int")
+        self.position = int(self.sampling_rate * position_ms / 1000)
+
+
+class BufferAudioSource(Rewindable):
     """
-    An :class:`AudioSource` that encapsulates and reads data from a memory buffer.
-    It implements methods from :class:`Rewindable` and is therefore a navigable :class:`AudioSource`.
+    An `AudioSource` that encapsulates and reads data from a memory buffer.
+
+    This class implements the `Rewindable` interface.
+    Parameters
+    ----------
+    data : bytes
+        audio data
+    sampling_rate : int, default: 16000
+        number of samples per second of audio data.
+    sample_width : int, default: 2
+        size in bytes of one audio sample. Possible values: 1, 2 or 4.
+    channels : int, default: 1
+        number of channels of audio data.
     """
-    
-    def __init__(self, data_buffer,
-                 sampling_rate = DEFAULT_SAMPLE_RATE,
-                 sample_width = DEFAULT_SAMPLE_WIDTH,
-                 channels = DEFAULT_NB_CHANNELS):
-        
-        if len(data_buffer) % (sample_width * channels) !=0:
-            raise ValueError("length of data_buffer must be a multiple of (sample_width * channels)")
-        
+
+    def __init__(
+        self, data, sampling_rate=16000, sample_width=2, channels=1,
+    ):
         AudioSource.__init__(self, sampling_rate, sample_width, channels)
-        self._buffer = data_buffer
-        self._index = 0
-        self._left = 0 if self._buffer is None else len(self._buffer)
+        check_audio_data(data, sample_width, channels)
+        self._data = data
+        self._sample_size_all_channels = sample_width * channels
+        self._current_position_bytes = 0
         self._is_open = False
-    
+
     def is_open(self):
         return self._is_open
-        
+
     def open(self):
         self._is_open = True
-    
+
     def close(self):
         self._is_open = False
         self.rewind()
-    
+
     def read(self, size):
         if not self._is_open:
-            raise IOError("Stream is not open")
-        
-        if self._left > 0:
-            
-            to_read = size * self.sample_width * self.channels       
-            if to_read > self._left:
-                to_read = self._left 
-                            
-            data = self._buffer[self._index: self._index + to_read]
-            self._index += to_read
-            self._left -= to_read
-            
+            raise AudioIOError("Stream is not open")
+        if size is None or size < 0:
+            offset = None
+        else:
+            bytes_to_read = self._sample_size_all_channels * size
+            offset = self._current_position_bytes + bytes_to_read
+        data = self._data[self._current_position_bytes : offset]
+        if data:
+            self._current_position_bytes += len(data)
             return data
-        
         return None
-    
-    def get_data_buffer(self):
-        """ Return all audio data as one string buffer. """
-        return self._buffer
-    
-    def set_data(self, data_buffer):
-        """ Set new data for this audio stream. 
-        
-        :Parameters:
-        
-            `data_buffer` : str, basestring, Bytes
-                a string buffer with a length multiple of (sample_width * channels)
-        """
-        if len(data_buffer) % (self.sample_width * self.channels) !=0:
-            raise ValueError("length of data_buffer must be a multiple of (sample_width * channels)")
-        self._buffer = data_buffer
-        self._index = 0
-        self._left = 0 if self._buffer is None else len(self._buffer)
-    
-    def append_data(self, data_buffer):
-        """ Append data to this audio stream
-        
-        :Parameters:
-        
-            `data_buffer` : str, basestring, Bytes
-                a buffer with a length multiple of (sample_width * channels)
-        """
-        
-        if len(data_buffer) % (self.sample_width * self.channels) !=0:
-            raise ValueError("length of data_buffer must be a multiple of (sample_width * channels)")
-        
-        self._buffer += data_buffer
-        self._left += len(data_buffer)
-
-    
+
+    @property
+    def data(self):
+        """Get raw audio data as a `bytes` object."""
+        return self._data
+
     def rewind(self):
-        self.set_position(0)
-    
-    def get_position(self):
-        return self._index / self.sample_width
-    
-    def get_time_position(self):
-        return float(self._index) / (self.sample_width * self.sampling_rate) 
-    
-    def set_position(self, position):
-        if position < 0:
-            raise ValueError("position must be >= 0")
-        
-        if self._buffer is None:
-            self._index = 0
-            self._left = 0
-            return
-         
-        position *= self.sample_width 
-        self._index = position if position < len(self._buffer) else len(self._buffer)
-        self._left = len(self._buffer) - self._index
+        self.position = 0
+
+    @property
+    def position(self):
+        """Get stream position in number of samples"""
+        return self._current_position_bytes // self._sample_size_all_channels
 
+    @position.setter
+    def position(self, position):
+        """Set stream position in number of samples."""
+        position *= self._sample_size_all_channels
+        if position < 0:
+            position += len(self.data)
+        if position < 0 or position > len(self.data):
+            raise IndexError("Position out of range")
+        self._current_position_bytes = position
 
-    def set_time_position(self, time_position): # time in seconds
-        position = int(self.sampling_rate * time_position)
-        self.set_position(position)
+    @property
+    def position_ms(self):
+        """Get stream position in milliseconds."""
+        return (self._current_position_bytes * 1000) // (
+            self._sample_size_all_channels * self.sampling_rate
+        )
 
+    @position_ms.setter
+    def position_ms(self, position_ms):
+        """Set stream position in milliseconds."""
+        if not isinstance(position_ms, int):
+            raise ValueError("position_ms should be an int")
+        self.position = int(self.sampling_rate * position_ms / 1000)
 
 
-class WaveAudioSource(AudioSource):
+class FileAudioSource(AudioSource):
     """
-    A class for an `AudioSource` that reads data from a wave file.
-    
-    :Parameters:
-        
-        `filename` :
-            path to a valid wave file
+    Base class `AudioSource`s that read audio data from a file.
+
+    Parameters
+    ----------
+    sampling_rate : int, default: 16000
+        number of samples per second of audio data.
+    sample_width : int, default: 2
+        size in bytes of one audio sample. Possible values: 1, 2 or 4.
+    channels : int, default: 1
+        number of channels of audio data.
     """
-    
-    def __init__(self, filename):
-        
-        self._filename = filename
+
+    def __init__(self, sampling_rate, sample_width, channels):
+        AudioSource.__init__(self, sampling_rate, sample_width, channels)
         self._audio_stream = None
-        
-        stream = wave.open(self._filename)
-        AudioSource.__init__(self, stream.getframerate(),
-                                   stream.getsampwidth(),
-                                   stream.getnchannels())
-        stream.close()
-    
-    
+
+    def __del__(self):
+        if self.is_open():
+            self.close()
+
     def is_open(self):
         return self._audio_stream is not None
- 
-    def open(self):
-        if(self._audio_stream is None):
-            self._audio_stream = wave.open(self._filename)
-      
-        
+
     def close(self):
         if self._audio_stream is not None:
             self._audio_stream.close()
             self._audio_stream = None
-        
-    
+
+    @abstractmethod
+    def _read_from_stream(self, size):
+        """Read data from stream"""
+
     def read(self, size):
+        if not self.is_open():
+            raise AudioIOError("Audio stream is not open")
+        data = self._read_from_stream(size)
+        if not data:
+            return None
+        return data
+
+
+class RawAudioSource(FileAudioSource):
+    """
+    A class for an `AudioSource` that reads data from a raw (headerless) audio
+    file.
+
+    This class should be used for large raw audio files to avoid loading the
+    whole data to memory.
+
+    Parameters
+    ----------
+    filename : str
+        path to a raw audio file.
+    sampling_rate : int
+        Number of samples per second of audio data.
+    sample_width : int
+        Size in bytes of one audio sample. Possible values : 1, 2, 4.
+    channels : int
+        Number of channels of audio data.
+    """
+
+    def __init__(self, file, sampling_rate, sample_width, channels):
+        FileAudioSource.__init__(self, sampling_rate, sample_width, channels)
+        self._file = file
+        self._audio_stream = None
+        self._sample_size = sample_width * channels
+
+    def open(self):
         if self._audio_stream is None:
-            raise IOError("Stream is not open")
+            self._audio_stream = open(self._file, "rb")
+
+    def _read_from_stream(self, size):
+        if size is None or size < 0:
+            bytes_to_read = None
         else:
-            data = self._audio_stream.readframes(size)
-            if data is None or len(data) < 1:
-                return None
-            return data
+            bytes_to_read = size * self._sample_size
+        data = self._audio_stream.read(bytes_to_read)
+        return data
+
+
+class WaveAudioSource(FileAudioSource):
+    """
+    A class for an `AudioSource` that reads data from a wave file.
+
+    This class should be used for large wave files to avoid loading the whole
+    data to memory.
+
+    Parameters
+    ----------
+    filename : str
+        path to a valid wave file.
+    """
+
+    def __init__(self, filename):
+        self._filename = filename
+        self._audio_stream = None
+        stream = wave.open(self._filename, "rb")
+        FileAudioSource.__init__(
+            self,
+            stream.getframerate(),
+            stream.getsampwidth(),
+            stream.getnchannels(),
+        )
+        stream.close()
+
+    def open(self):
+        if self._audio_stream is None:
+            self._audio_stream = wave.open(self._filename)
+
+    def _read_from_stream(self, size):
+        if size is None or size < 0:
+            size = -1
+        return self._audio_stream.readframes(size)
 
 
 class PyAudioSource(AudioSource):
     """
-    A class for an `AudioSource` that reads data the built-in microphone using PyAudio. 
+    A class for an `AudioSource` that reads data from built-in microphone using
+    PyAudio (https://people.csail.mit.edu/hubert/pyaudio/).
+
+    Parameters
+    ----------
+    sampling_rate : int, default: 16000
+        number of samples per second of audio data.
+    sample_width : int, default: 2
+        size in bytes of one audio sample. Possible values: 1, 2 or 4.
+    channels : int, default: 1
+        number of channels of audio data.
+    frames_per_buffer : int, default: 1024
+        PyAudio number of frames per buffer.
+    input_device_index: None or int, default: None
+        PyAudio index of audio device to read audio data from. If None default
+        device is used.
     """
-    
-    def __init__(self, sampling_rate = DEFAULT_SAMPLE_RATE,
-                 sample_width = DEFAULT_SAMPLE_WIDTH,
-                 channels = DEFAULT_NB_CHANNELS,
-                 frames_per_buffer = 1024):
-        
-        
+
+    def __init__(
+        self,
+        sampling_rate=16000,
+        sample_width=2,
+        channels=1,
+        frames_per_buffer=1024,
+        input_device_index=None,
+    ):
+
         AudioSource.__init__(self, sampling_rate, sample_width, channels)
         self._chunk_size = frames_per_buffer
-        
+        self.input_device_index = input_device_index
+
         import pyaudio
+
         self._pyaudio_object = pyaudio.PyAudio()
-        self._pyaudio_format = self._pyaudio_object.get_format_from_width(self.sample_width) 
+        self._pyaudio_format = self._pyaudio_object.get_format_from_width(
+            self.sample_width
+        )
         self._audio_stream = None
 
-    
     def is_open(self):
         return self._audio_stream is not None
-    
+
     def open(self):
-        self._audio_stream = self._pyaudio_object.open(format = self._pyaudio_format,
-                                                   channels = self.channels,
-                                                   rate = self.sampling_rate,
-                                                   input = True,
-                                                   output = False,
-                                                   frames_per_buffer = self._chunk_size)
-        
-        
+        self._audio_stream = self._pyaudio_object.open(
+            format=self._pyaudio_format,
+            channels=self.channels,
+            rate=self.sampling_rate,
+            input=True,
+            output=False,
+            input_device_index=self.input_device_index,
+            frames_per_buffer=self._chunk_size,
+        )
+
     def close(self):
         if self._audio_stream is not None:
             self._audio_stream.stop_stream()
             self._audio_stream.close()
             self._audio_stream = None
-            
-    
+
     def read(self, size):
         if self._audio_stream is None:
             raise IOError("Stream is not open")
-        
         if self._audio_stream.is_active():
             data = self._audio_stream.read(size)
             if data is None or len(data) < 1:
                 return None
             return data
-        
         return None
-    
 
-class StdinAudioSource(AudioSource):
+
+class StdinAudioSource(FileAudioSource):
     """
-    A class for an :class:`AudioSource` that reads data from standard input.
+    A class for an `AudioSource` that reads data from standard input.
+
+    Parameters
+    ----------
+    sampling_rate : int, default: 16000
+        number of samples per second of audio data.
+    sample_width : int, default: 2
+        size in bytes of one audio sample. Possible values: 1, 2 or 4.
+    channels : int, default: 1
+        number of channels of audio data.
     """
-    
-    def __init__(self, sampling_rate = DEFAULT_SAMPLE_RATE,
-                 sample_width = DEFAULT_SAMPLE_WIDTH,
-                 channels = DEFAULT_NB_CHANNELS):
-    
-        AudioSource.__init__(self, sampling_rate, sample_width, channels)
+
+    def __init__(
+        self, sampling_rate=16000, sample_width=2, channels=1,
+    ):
+        FileAudioSource.__init__(self, sampling_rate, sample_width, channels)
         self._is_open = False
-    
-    
+        self._sample_size = sample_width * channels
+        self._stream = sys.stdin.buffer
+
     def is_open(self):
         return self._is_open
-        
+
     def open(self):
         self._is_open = True
-    
+
     def close(self):
         self._is_open = False
-        
-    def read(self, size):
-        if not self._is_open:
-            raise IOError("Stream is not open")
-        
-        to_read = size * self.sample_width * self.channels
-        data = sys.stdin.read(to_read)
-        
-        if data is None or len(data) < 1:
-            return None
-        
-        return data
-       
-           
-class PyAudioPlayer():
+
+    def _read_from_stream(self, size):
+        bytes_to_read = size * self._sample_size
+        data = self._stream.read(bytes_to_read)
+        if data:
+            return data
+        return None
+
+
+def _make_tqdm_progress_bar(iterable, total, duration, **tqdm_kwargs):
+    fmt = tqdm_kwargs.get("bar_format", DEFAULT_BAR_FORMAT_TQDM)
+    fmt = fmt.replace("{duration}", "{:.3f}".format(duration))
+    tqdm_kwargs["bar_format"] = fmt
+
+    tqdm_kwargs["ncols"] = tqdm_kwargs.get("ncols", DEFAULT_NCOLS_TQDM)
+    tqdm_kwargs["mininterval"] = tqdm_kwargs.get(
+        "mininterval", DEFAULT_MIN_INTERVAL_TQDM
+    )
+    return _tqdm(iterable, total=total, **tqdm_kwargs)
+
+
+class PyAudioPlayer:
     """
     A class for audio playback using Pyaudio
+    (https://people.csail.mit.edu/hubert/pyaudio/).
+
+    Parameters
+    ----------
+    sampling_rate : int, default: 16000
+        number of samples per second of audio data.
+    sample_width : int, default: 2
+        size in bytes of one audio sample. Possible values: 1, 2 or 4.
+    channels : int, default: 1
+        number of channels of audio data.
     """
-    
-    def __init__(self, sampling_rate = DEFAULT_SAMPLE_RATE,
-                 sample_width = DEFAULT_SAMPLE_WIDTH,
-                 channels = DEFAULT_NB_CHANNELS):
-        if not sample_width in (1, 2, 4):
-            raise ValueError("Sample width must be one of: 1, 2 or 4 (bytes)")
-        
+
+    def __init__(
+        self, sampling_rate=16000, sample_width=2, channels=1,
+    ):
+        if sample_width not in (1, 2, 4):
+            raise ValueError("Sample width in bytes must be one of 1, 2 or 4")
+
         self.sampling_rate = sampling_rate
         self.sample_width = sample_width
         self.channels = channels
-        
+
         import pyaudio
+
         self._p = pyaudio.PyAudio()
-        self.stream = self._p.open(format = self._p.get_format_from_width(self.sample_width),
-         channels = self.channels, rate = self.sampling_rate,
-         input = False, output = True)
-        
-    def play(self, data):
+        self.stream = self._p.open(
+            format=self._p.get_format_from_width(self.sample_width),
+            channels=self.channels,
+            rate=self.sampling_rate,
+            input=False,
+            output=True,
+        )
+
+    def play(self, data, progress_bar=False, **progress_bar_kwargs):
+        chunk_gen, nb_chunks = self._chunk_data(data)
+        if progress_bar and _WITH_TQDM:
+            duration = len(data) / (
+                self.sampling_rate * self.sample_width * self.channels
+            )
+            chunk_gen = _make_tqdm_progress_bar(
+                chunk_gen,
+                total=nb_chunks,
+                duration=duration,
+                **progress_bar_kwargs
+            )
         if self.stream.is_stopped():
             self.stream.start_stream()
-        
-        for chunk in self._chunk_data(data):
-            self.stream.write(chunk)
-            
+        try:
+            for chunk in chunk_gen:
+                self.stream.write(chunk)
+        except KeyboardInterrupt:
+            pass
         self.stream.stop_stream()
-    
-    def  stop(self):
+
+    def stop(self):
         if not self.stream.is_stopped():
             self.stream.stop_stream()
         self.stream.close()
         self._p.terminate()
-    
+
     def _chunk_data(self, data):
         # make audio chunks of 100 ms to allow interruption (like ctrl+c)
-        chunk_size = int((self.sampling_rate * self.sample_width * self.channels) / 10)
-        start = 0
-        while start < len(data):
-            yield data[start : start + chunk_size]
-            start += chunk_size
-        
-
-def from_file(filename):
-    """
-    Create an `AudioSource` object using the audio file specified by `filename`.
-    The appropriate :class:`AudioSource` class is guessed from file's extension.
-    
-    :Parameters:
-    
-        `filename` :
-            path to an audio file.
-        
-    :Returns:
-    
-        an `AudioSource` object that reads data from the given file.
-    
-    """
-    
-    if filename.lower().endswith(".wav"):
-        return WaveAudioSource(filename)
-    
-    raise Exception("Can not create an AudioSource object from '%s'" %(filename))
-
-
-def player_for(audio_source):
-    """
-    Return a :class:`PyAudioPlayer` that can play data from `audio_source`.
-    
-    :Parameters:
-    
-        `audio_source` : 
-            an `AudioSource` object.
-    
-    :Returns:
-    
-        `PyAudioPlayer` that has the same sampling rate, sample width and number of channels
-        as `audio_source`.
-    """
-    
-    return PyAudioPlayer(audio_source.get_sampling_rate(),
-            audio_source.get_sample_width(),
-            audio_source.get_channels())
-    
-    
+        bytes_1_sec = self.sampling_rate * self.sample_width * self.channels
+        chunk_size = bytes_1_sec // 10
+        # make sure chunk_size is a multiple of sample_width * channels
+        chunk_size -= chunk_size % (self.sample_width * self.channels)
+        nb_chunks, rest = divmod(len(data), chunk_size)
+        if rest > 0:
+            nb_chunks += 1
+        chunk_gen = (
+            data[i : i + chunk_size] for i in range(0, len(data), chunk_size)
+        )
+        return chunk_gen, nb_chunks
+
+
+def player_for(source):
+    """
+    Return an `AudioPlayer` compatible with `source` (i.e., has the same
+    sampling rate, sample width and number of channels).
+
+    Parameters
+    ----------
+    source : AudioSource
+        An object that has `sampling_rate`, `sample_width` and `sample_width`
+        attributes.
+
+    Returns
+    -------
+    player : PyAudioPlayer
+        An audio player that has the same sampling rate, sample width
+        and number of channels as `source`.
+    """
+    return PyAudioPlayer(
+        source.sampling_rate, source.sample_width, source.channels
+    )
+
+
+def get_audio_source(input=None, **kwargs):
+    """
+    Create and return an AudioSource from input.
+
+    Parameters
+    ----------
+    input : str, bytes, "-" or None (default)
+        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.
+    kwargs
+        audio parameters used to build the `AudioSource` object. Depending on
+        the nature of `input`, theses may be omitted (e.g., when `input` is an
+        audio file in a popular audio format such as wav, ogg, flac, etc.) or
+        include parameters such as `sampling_rate`, `sample_width`, `channels`
+        (or their respective short name versions `sr`, `sw` and `ch`) if `input`
+        is a path to a raw (headerless) audio file, a bytes object for raw audio
+        data or None (to read data from built-in microphone). See the respective
+        `AudioSource` classes from more information about possible parameters.
+
+    Returns
+    -------
+    source : AudioSource
+        audio source created from input parameters
+    """
+    if input == "-":
+        return StdinAudioSource(*_get_audio_parameters(kwargs))
 
+    if isinstance(input, bytes):
+        return BufferAudioSource(input, *_get_audio_parameters(kwargs))
+
+    # read data from a file
+    if input is not None:
+        return from_file(filename=input, **kwargs)
+
+    # read data from microphone via pyaudio
+    else:
+        frames_per_buffer = kwargs.get("frames_per_buffer", 1024)
+        input_device_index = kwargs.get("input_device_index")
+        return PyAudioSource(
+            *_get_audio_parameters(kwargs),
+            frames_per_buffer=frames_per_buffer,
+            input_device_index=input_device_index
+        )
+
+
+def _load_raw(file, sampling_rate, sample_width, channels, large_file=False):
+    """
+    Load a raw audio file with standard Python. If `large_file` is True, return
+    a `RawAudioSource` object that reads data lazily from disk, otherwise load
+    all data to memory and return a `BufferAudioSource` object.
+
+    Parameters
+    ----------
+    file : str
+        path to a raw audio data file.
+    sampling_rate : int
+        sampling rate of audio data.
+    sample_width : int
+        size in bytes of one audio sample.
+    channels : int
+        number of channels of audio data.
+    large_file : bool
+        if True, return a `RawAudioSource` otherwise a `BufferAudioSource`
+        object.
+
+    Returns
+    -------
+    source : RawAudioSource or BufferAudioSource
+        an `AudioSource` that reads data from input file.
+    """
+    if None in (sampling_rate, sample_width, channels):
+        raise AudioParameterError(
+            "All audio parameters are required for raw audio files"
+        )
+
+    if large_file:
+        return RawAudioSource(
+            file,
+            sampling_rate=sampling_rate,
+            sample_width=sample_width,
+            channels=channels,
+        )
+
+    with open(file, "rb") as fp:
+        data = fp.read()
+    return BufferAudioSource(
+        data,
+        sampling_rate=sampling_rate,
+        sample_width=sample_width,
+        channels=channels,
+    )
+
+
+def _load_wave(file, large_file=False):
+    """
+    Load a wave audio file with standard Python. If `large_file` is True, return
+    a `WaveAudioSource` object that reads data lazily from disk, otherwise load
+    all data to memory and return a `BufferAudioSource` object.
+
+    Parameters
+    ----------
+    file : str
+        path to a wav audio data file
+    large_file : bool
+        if True, return a `WaveAudioSource` otherwise a `BufferAudioSource`
+        object.
+
+    Returns
+    -------
+    source : WaveAudioSource or BufferAudioSource
+        an `AudioSource` that reads data from input file.
+    """
+    if large_file:
+        return WaveAudioSource(file)
+    with wave.open(file) as fp:
+        channels = fp.getnchannels()
+        srate = fp.getframerate()
+        swidth = fp.getsampwidth()
+        data = fp.readframes(-1)
+    return BufferAudioSource(
+        data, sampling_rate=srate, sample_width=swidth, channels=channels
+    )
+
+
+def _load_with_pydub(file, audio_format=None):
+    """
+    Open compressed audio or video file using pydub. If a video file
+    is passed, its audio track(s) are extracted and loaded.
+
+    Parameters
+    ----------
+    file : str
+        path to audio file.
+    audio_format : str, default: None
+        string, audio/video file format if known (e.g. raw, webm, wav, ogg)
+
+    Returns
+    -------
+    source : BufferAudioSource
+        an `AudioSource` that reads data from input file.
+    """
+    func_dict = {
+        "mp3": AudioSegment.from_mp3,
+        "ogg": AudioSegment.from_ogg,
+        "flv": AudioSegment.from_flv,
+    }
+    open_function = func_dict.get(audio_format, AudioSegment.from_file)
+    segment = open_function(file)
+    return BufferAudioSource(
+        data=segment.raw_data,
+        sampling_rate=segment.frame_rate,
+        sample_width=segment.sample_width,
+        channels=segment.channels,
+    )
+
+
+def from_file(filename, audio_format=None, large_file=False, **kwargs):
+    """
+    Read audio data from `filename` and return an `AudioSource` object.
+    if `audio_format` is None, the appropriate `AudioSource` class is guessed
+    from file's extension. `filename` can be a compressed audio or video file.
+    This will require installing `pydub` (https://github.com/jiaaro/pydub).
+
+    The normal behavior is to load all audio data to memory from which a
+    :class:`BufferAudioSource` object is created. This should be convenient
+    most     of the time unless audio file is very large. In that case, and
+    in order to load audio data in lazy manner (i.e. read data from disk each
+    time :func:`AudioSource.read` is called), `large_file` should be True.
+
+    Note that the current implementation supports only wave and raw formats for
+    lazy audio loading.
+
+    If an audio format is `raw`, the following keyword arguments are required:
+
+        - `sampling_rate`, `sr`: int,  sampling rate of audio data.
+        - `sample_width`, `sw`: int, size in bytes of one audio sample.
+        - `channels`, `ch`: int, number of channels of audio data.
+
+    See also
+    --------
+    :func:`to_file`.
+
+    Parameters
+    ----------
+    filename : str
+        path to input audio or video file.
+    audio_format : str
+        audio format used to save data  (e.g. raw, webm, wav, ogg).
+    large_file : bool, default: False
+        if True, audio won't fully be loaded to memory but only when a window
+        is read from disk.
+
+
+    Other Parameters
+    ----------------
+    sampling_rate, sr: int
+        sampling rate of audio data
+    sample_width : int
+        sample width (i.e. number of bytes used to represent one audio sample)
+    channels : int
+        number of channels of audio data
+
+    Returns
+    -------
+    audio_source : AudioSource
+        an :class:`AudioSource` object that reads data from input file.
+
+    Raises
+    ------
+    `AudioIOError`
+        raised if audio data cannot be read in the given
+        format or if `format` is `raw` and one or more audio parameters are missing.
+    """
+    audio_format = _guess_audio_format(audio_format, filename)
+
+    if audio_format == "raw":
+        srate, swidth, channels = _get_audio_parameters(kwargs)
+        return _load_raw(filename, srate, swidth, channels, large_file)
+
+    if audio_format in ["wav", "wave"]:
+        return _load_wave(filename, large_file)
+    if large_file:
+        err_msg = "if 'large_file` is True file format should be raw or wav"
+        raise AudioIOError(err_msg)
+    if _WITH_PYDUB:
+        return _load_with_pydub(filename, audio_format=audio_format)
+    else:
+        raise AudioIOError(
+            "pydub is required for audio formats other than raw or wav"
+        )
+
+
+def _save_raw(data, file):
+    """
+    Saves audio data as a headerless (i.e. raw) file.
+    See also :func:`to_file`.
+    """
+    with open(file, "wb") as fp:
+        fp.write(data)
+
+
+def _save_wave(data, file, sampling_rate, sample_width, channels):
+    """
+    Saves audio data to a wave file.
+    See also :func:`to_file`.
+    """
+    if None in (sampling_rate, sample_width, channels):
+        raise AudioParameterError(
+            "All audio parameters are required to save wave audio files"
+        )
+    with wave.open(file, "w") as fp:
+        fp.setframerate(sampling_rate)
+        fp.setsampwidth(sample_width)
+        fp.setnchannels(channels)
+        fp.writeframes(data)
+
+
+def _save_with_pydub(
+    data, file, audio_format, sampling_rate, sample_width, channels
+):
+    """
+    Saves audio data with pydub (https://github.com/jiaaro/pydub).
+    See also :func:`to_file`.
+    """
+    segment = AudioSegment(
+        data,
+        frame_rate=sampling_rate,
+        sample_width=sample_width,
+        channels=channels,
+    )
+    with open(file, "wb") as fp:
+        segment.export(fp, format=audio_format)
+
+
+def to_file(data, file, audio_format=None, **kwargs):
+    """
+    Writes audio data to file. If `audio_format` is `None`, output
+    audio format will be guessed from extension. If `audio_format`
+    is `None` and `file` comes without an extension then audio
+    data will be written as a raw audio file.
+
+    Parameters
+    ----------
+    data : bytes-like
+        audio data to be written. Can be a `bytes`, `bytearray`,
+        `memoryview`, `array` or `numpy.ndarray` object.
+    file : str
+        path to output audio file.
+    audio_format : str
+        audio format used to save data (e.g. raw, webm, wav, ogg)
+    kwargs: dict
+        If an audio format other than `raw` is used, the following keyword
+        arguments are required:
+
+        - `sampling_rate`, `sr`: int,  sampling rate of audio data.
+        - `sample_width`, `sw`: int, size in bytes of one audio sample.
+        - `channels`, `ch`: int, number of channels of audio data.
+
+    Raises
+    ------
+    `AudioParameterError` if output format is different than raw and one or more
+    audio parameters are missing. `AudioIOError` if audio data cannot be written
+    in the desired format.
+    """
+    audio_format = _guess_audio_format(audio_format, file)
+    if audio_format in (None, "raw"):
+        _save_raw(data, file)
+        return
+    try:
+        sampling_rate, sample_width, channels = _get_audio_parameters(kwargs)
+    except AudioParameterError as exc:
+        err_message = "All audio parameters are required to save formats "
+        "other than raw. Error detail: {}".format(exc)
+        raise AudioParameterError(err_message)
+    if audio_format in ("wav", "wave"):
+        _save_wave(data, file, sampling_rate, sample_width, channels)
+    elif _WITH_PYDUB:
+        _save_with_pydub(
+            data, file, audio_format, sampling_rate, sample_width, channels
+        )
+    else:
+        err_message = "cannot write file format {} (file name: {})"
+        raise AudioIOError(err_message.format(audio_format, file))
diff --git a/libs/auditok/plotting.py b/libs/auditok/plotting.py
new file mode 100755
index 000000000..eca5877f4
--- /dev/null
+++ b/libs/auditok/plotting.py
@@ -0,0 +1,150 @@
+import matplotlib.pyplot as plt
+import numpy as np
+
+AUDITOK_PLOT_THEME = {
+    "figure": {"facecolor": "#482a36", "alpha": 0.2},
+    "plot": {"facecolor": "#282a36"},
+    "energy_threshold": {
+        "color": "#e31f8f",
+        "linestyle": "--",
+        "linewidth": 1,
+    },
+    "signal": {"color": "#40d970", "linestyle": "-", "linewidth": 1},
+    "detections": {
+        "facecolor": "#777777",
+        "edgecolor": "#ff8c1a",
+        "linewidth": 1,
+        "alpha": 0.75,
+    },
+}
+
+
+def _make_time_axis(nb_samples, sampling_rate):
+    sample_duration = 1 / sampling_rate
+    x = np.linspace(0, sample_duration * (nb_samples - 1), nb_samples)
+    return x
+
+
+def _plot_line(x, y, theme, xlabel=None, ylabel=None, **kwargs):
+    color = theme.get("color", theme.get("c"))
+    ls = theme.get("linestyle", theme.get("ls"))
+    lw = theme.get("linewidth", theme.get("lw"))
+    plt.plot(x, y, c=color, ls=ls, lw=lw, **kwargs)
+    plt.xlabel(xlabel, fontsize=8)
+    plt.ylabel(ylabel, fontsize=8)
+
+
+def _plot_detections(subplot, detections, theme):
+    fc = theme.get("facecolor", theme.get("fc"))
+    ec = theme.get("edgecolor", theme.get("ec"))
+    ls = theme.get("linestyle", theme.get("ls"))
+    lw = theme.get("linewidth", theme.get("lw"))
+    alpha = theme.get("alpha")
+    for (start, end) in detections:
+        subplot.axvspan(start, end, fc=fc, ec=ec, ls=ls, lw=lw, alpha=alpha)
+
+
+def plot(
+    audio_region,
+    scale_signal=True,
+    detections=None,
+    energy_threshold=None,
+    show=True,
+    figsize=None,
+    save_as=None,
+    dpi=120,
+    theme="auditok",
+):
+    y = np.asarray(audio_region)
+    if len(y.shape) == 1:
+        y = y.reshape(1, -1)
+    nb_subplots, nb_samples = y.shape
+    sampling_rate = audio_region.sampling_rate
+    time_axis = _make_time_axis(nb_samples, sampling_rate)
+    if energy_threshold is not None:
+        eth_log10 = energy_threshold * np.log(10) / 10
+        amplitude_threshold = np.sqrt(np.exp(eth_log10))
+    else:
+        amplitude_threshold = None
+    if detections is None:
+        detections = []
+    else:
+        # End of detection corresponds to the end of the last sample but
+        # to stay compatible with the time axis of signal plotting we want end
+        # of detection to correspond to the *start* of the that last sample.
+        detections = [
+            (start, end - (1 / sampling_rate)) for (start, end) in detections
+        ]
+    if theme == "auditok":
+        theme = AUDITOK_PLOT_THEME
+
+    fig = plt.figure(figsize=figsize, dpi=dpi)
+    fig_theme = theme.get("figure", theme.get("fig", {}))
+    fig_fc = fig_theme.get("facecolor", fig_theme.get("ffc"))
+    fig_alpha = fig_theme.get("alpha", 1)
+    fig.patch.set_facecolor(fig_fc)
+    fig.patch.set_alpha(fig_alpha)
+
+    plot_theme = theme.get("plot", {})
+    plot_fc = plot_theme.get("facecolor", plot_theme.get("pfc"))
+
+    if nb_subplots > 2 and nb_subplots % 2 == 0:
+        nb_rows = nb_subplots // 2
+        nb_columns = 2
+    else:
+        nb_rows = nb_subplots
+        nb_columns = 1
+
+    for sid, samples in enumerate(y, 1):
+        ax = fig.add_subplot(nb_rows, nb_columns, sid)
+        ax.set_facecolor(plot_fc)
+        if scale_signal:
+            std = samples.std()
+            if std > 0:
+                mean = samples.mean()
+                std = samples.std()
+                samples = (samples - mean) / std
+                max_ = samples.max()
+                plt.ylim(-1.5 * max_, 1.5 * max_)
+        if amplitude_threshold is not None:
+            if scale_signal and std > 0:
+                amp_th = (amplitude_threshold - mean) / std
+            else:
+                amp_th = amplitude_threshold
+            eth_theme = theme.get("energy_threshold", theme.get("eth", {}))
+            _plot_line(
+                [time_axis[0], time_axis[-1]],
+                [amp_th] * 2,
+                eth_theme,
+                label="Detection threshold",
+            )
+            if sid == 1:
+                legend = plt.legend(
+                    ["Detection threshold"],
+                    facecolor=fig_fc,
+                    framealpha=0.1,
+                    bbox_to_anchor=(0.0, 1.15, 1.0, 0.102),
+                    loc=2,
+                )
+                legend = plt.gca().add_artist(legend)
+
+        signal_theme = theme.get("signal", {})
+        _plot_line(
+            time_axis,
+            samples,
+            signal_theme,
+            xlabel="Time (seconds)",
+            ylabel="Signal{}".format(" (scaled)" if scale_signal else ""),
+        )
+        detections_theme = theme.get("detections", {})
+        _plot_detections(ax, detections, detections_theme)
+        plt.title("Channel {}".format(sid), fontsize=10)
+
+        plt.xticks(fontsize=8)
+        plt.yticks(fontsize=8)
+    plt.tight_layout()
+
+    if save_as is not None:
+        plt.savefig(save_as, dpi=dpi)
+    if show:
+        plt.show()
diff --git a/libs/auditok/signal.py b/libs/auditok/signal.py
new file mode 100644
index 000000000..3f00fb9e5
--- /dev/null
+++ b/libs/auditok/signal.py
@@ -0,0 +1,179 @@
+"""
+Module for basic audio signal processing and array operations.
+
+.. autosummary::
+    :toctree: generated/
+
+    to_array
+    extract_single_channel
+    compute_average_channel
+    compute_average_channel_stereo
+    separate_channels
+    calculate_energy_single_channel
+    calculate_energy_multichannel
+"""
+from array import array as array_
+import audioop
+import math
+
+FORMAT = {1: "b", 2: "h", 4: "i"}
+_EPSILON = 1e-10
+
+
+def to_array(data, sample_width, channels):
+    """Extract individual channels of audio data and return a list of arrays of
+    numeric samples. This will always return a list of `array.array` objects
+    (one per channel) even if audio data is mono.
+
+    Parameters
+    ----------
+    data : bytes
+        raw audio data.
+    sample_width : int
+        size in bytes of one audio sample (one channel considered).
+
+    Returns
+    -------
+    samples_arrays : list
+        list of arrays of audio samples.
+    """
+    fmt = FORMAT[sample_width]
+    if channels == 1:
+        return [array_(fmt, data)]
+    return separate_channels(data, fmt, channels)
+
+
+def extract_single_channel(data, fmt, channels, selected):
+    samples = array_(fmt, data)
+    return samples[selected::channels]
+
+
+def compute_average_channel(data, fmt, channels):
+    """
+    Compute and return average channel of multi-channel audio data. If the
+    number of channels is 2, use :func:`compute_average_channel_stereo` (much
+    faster). This function uses satandard `array` module to convert `bytes` data
+    into an array of numeric values.
+
+    Parameters
+    ----------
+    data : bytes
+        multi-channel audio data to mix down.
+    fmt : str
+        format (single character) to pass to `array.array` to convert `data`
+        into an array of samples. This should be "b" if audio data's sample width
+        is 1, "h" if it's 2 and "i" if it's 4.
+    channels : int
+        number of channels of audio data.
+
+    Returns
+    -------
+    mono_audio : bytes
+        mixed down audio data.
+    """
+    all_channels = array_(fmt, data)
+    mono_channels = [
+        array_(fmt, all_channels[ch::channels]) for ch in range(channels)
+    ]
+    avg_arr = array_(
+        fmt,
+        (round(sum(samples) / channels) for samples in zip(*mono_channels)),
+    )
+    return avg_arr
+
+
+def compute_average_channel_stereo(data, sample_width):
+    """Compute and return average channel of stereo audio data. This function
+    should be used when the number of channels is exactly 2 because in that
+    case we can use standard `audioop` module which *much* faster then calling
+    :func:`compute_average_channel`.
+
+    Parameters
+    ----------
+    data : bytes
+        2-channel audio data to mix down.
+    sample_width : int
+        size in bytes of one audio sample (one channel considered).
+
+    Returns
+    -------
+    mono_audio : bytes
+        mixed down audio data.
+    """
+    fmt = FORMAT[sample_width]
+    arr = array_(fmt, audioop.tomono(data, sample_width, 0.5, 0.5))
+    return arr
+
+
+def separate_channels(data, fmt, channels):
+    """Create a list of arrays of audio samples (`array.array` objects), one for
+    each channel.
+
+    Parameters
+    ----------
+    data : bytes
+        multi-channel audio data to mix down.
+    fmt : str
+        format (single character) to pass to `array.array` to convert `data`
+        into an array of samples. This should be "b" if audio data's sample width
+        is 1, "h" if it's 2 and "i" if it's 4.
+    channels : int
+        number of channels of audio data.
+
+    Returns
+    -------
+    channels_arr : list
+        list of audio channels, each as a standard `array.array`.
+    """
+    all_channels = array_(fmt, data)
+    mono_channels = [
+        array_(fmt, all_channels[ch::channels]) for ch in range(channels)
+    ]
+    return mono_channels
+
+
+def calculate_energy_single_channel(data, sample_width):
+    """Calculate the energy of mono audio data. Energy is computed as:
+
+    .. math:: energy = 20 \log(\sqrt({1}/{N}\sum_{i}^{N}{a_i}^2)) % # noqa: W605
+
+    where `a_i` is the i-th audio sample and `N` is the number of audio samples
+    in data.
+
+    Parameters
+    ----------
+    data : bytes
+        single-channel audio data.
+    sample_width : int
+        size in bytes of one audio sample.
+
+    Returns
+    -------
+    energy : float
+        energy of audio signal.
+    """
+    energy_sqrt = max(audioop.rms(data, sample_width), _EPSILON)
+    return 20 * math.log10(energy_sqrt)
+
+
+def calculate_energy_multichannel(x, sample_width, aggregation_fn=max):
+    """Calculate the energy of multi-channel audio data. Energy is calculated
+    channel-wise. An aggregation function is applied to the resulting energies
+    (default: `max`). Also see :func:`calculate_energy_single_channel`.
+
+    Parameters
+    ----------
+    data : bytes
+        single-channel audio data.
+    sample_width : int
+        size in bytes of one audio sample (one channel considered).
+    aggregation_fn : callable, default: max
+        aggregation function to apply to the resulting per-channel energies.
+
+    Returns
+    -------
+    energy : float
+        aggregated energy of multi-channel audio signal.
+    """
+    energies = (calculate_energy_single_channel(xi, sample_width) for xi in x)
+    return aggregation_fn(energies)
diff --git a/libs/auditok/signal_numpy.py b/libs/auditok/signal_numpy.py
new file mode 100644
index 000000000..bf5425197
--- /dev/null
+++ b/libs/auditok/signal_numpy.py
@@ -0,0 +1,30 @@
+import numpy as np
+from .signal import (
+    compute_average_channel_stereo,
+    calculate_energy_single_channel,
+    calculate_energy_multichannel,
+)
+
+FORMAT = {1: np.int8, 2: np.int16, 4: np.int32}
+
+
+def to_array(data, sample_width, channels):
+    fmt = FORMAT[sample_width]
+    if channels == 1:
+        return np.frombuffer(data, dtype=fmt).astype(np.float64)
+    return separate_channels(data, fmt, channels).astype(np.float64)
+
+
+def extract_single_channel(data, fmt, channels, selected):
+    samples = np.frombuffer(data, dtype=fmt)
+    return np.asanyarray(samples[selected::channels], order="C")
+
+
+def compute_average_channel(data, fmt, channels):
+    array = np.frombuffer(data, dtype=fmt).astype(np.float64)
+    return array.reshape(-1, channels).mean(axis=1).round().astype(fmt)
+
+
+def separate_channels(data, fmt, channels):
+    array = np.frombuffer(data, dtype=fmt)
+    return np.asanyarray(array.reshape(-1, channels).T, order="C")
diff --git a/libs/auditok/util.py b/libs/auditok/util.py
index d46a8899c..f29eb9bf3 100644
--- a/libs/auditok/util.py
+++ b/libs/auditok/util.py
@@ -1,448 +1,624 @@
 """
-Class summary
-=============
-
 .. autosummary::
+    :toctree: generated/
 
-        DataSource
-        StringDataSource
-        ADSFactory
-        ADSFactory.AudioDataSource
-        ADSFactory.ADSDecorator
-        ADSFactory.OverlapADS
-        ADSFactory.LimiterADS
-        ADSFactory.RecorderADS
-        DataValidator
-        AudioEnergyValidator
-
+    AudioEnergyValidator
+    AudioReader
+    Recorder
+    make_duration_formatter
+    make_channel_selector
 """
+from abc import ABC, abstractmethod
+import warnings
+from functools import partial
+from .io import (
+    AudioIOError,
+    AudioSource,
+    from_file,
+    BufferAudioSource,
+    PyAudioSource,
+    get_audio_source,
+)
+from .exceptions import (
+    DuplicateArgument,
+    TooSamllBlockDuration,
+    TimeFormatError,
+)
 
+try:
+    from . import signal_numpy as signal
+except ImportError:
+    from . import signal
 
-from abc import ABCMeta, abstractmethod
-import math
-from array import array
-from .io import Rewindable, from_file, BufferAudioSource, PyAudioSource
-from .exceptions import DuplicateArgument
-import sys
 
+__all__ = [
+    "make_duration_formatter",
+    "make_channel_selector",
+    "DataSource",
+    "DataValidator",
+    "StringDataSource",
+    "ADSFactory",
+    "AudioDataSource",
+    "AudioReader",
+    "Recorder",
+    "AudioEnergyValidator",
+]
 
-try:
-    import numpy
-    _WITH_NUMPY = True
-except ImportError as e:
-    _WITH_NUMPY = False
-    
-try:
-    from builtins import str
-    basestring = str
-except ImportError as e:
-    if sys.version_info >= (3, 0):
-        basestring = str
-    
-    
-
-__all__ = ["DataSource", "DataValidator", "StringDataSource", "ADSFactory", "AudioEnergyValidator"]
-    
-
-class DataSource():
+
+def make_duration_formatter(fmt):
+    """
+    Make and return a function used to format durations in seconds. Accepted
+    format directives are:
+
+    - ``%S`` : absolute number of seconds with 3 decimals. This direction should
+      be used alone.
+    - ``%i`` : milliseconds
+    - ``%s`` : seconds
+    - ``%m`` : minutes
+    - ``%h`` : hours
+
+    These last 4 directives should all be specified. They can be placed anywhere
+    in the input string.
+
+    Parameters
+    ----------
+    fmt : str
+        duration format.
+
+    Returns
+    -------
+    formatter : callable
+        a function that takes a duration in seconds (float) and returns a string
+        that corresponds to that duration.
+
+    Raises
+    ------
+    TimeFormatError
+        if the format contains an unknown directive.
+
+    Examples
+    --------
+
+    Using ``%S``:
+
+    .. code:: python
+
+        formatter = make_duration_formatter("%S")
+        formatter(123.589)
+        '123.589'
+        formatter(123)
+        '123.000'
+
+    Using the other directives:
+
+    .. code:: python
+
+        formatter = make_duration_formatter("%h:%m:%s.%i")
+        formatter(3600+120+3.25)
+        '01:02:03.250'
+
+        formatter = make_duration_formatter("%h hrs, %m min, %s sec and %i ms")
+        formatter(3600+120+3.25)
+        '01 hrs, 02 min, 03 sec and 250 ms'
+
+        # omitting one of the 4 directives might result in a wrong duration
+        formatter = make_duration_formatter("%m min, %s sec and %i ms")
+        formatter(3600+120+3.25)
+        '02 min, 03 sec and 250 ms'
+    """
+    if fmt == "%S":
+
+        def fromatter(seconds):
+            return "{:.3f}".format(seconds)
+
+    elif fmt == "%I":
+
+        def fromatter(seconds):
+            return "{0}".format(int(seconds * 1000))
+
+    else:
+        fmt = fmt.replace("%h", "{hrs:02d}")
+        fmt = fmt.replace("%m", "{mins:02d}")
+        fmt = fmt.replace("%s", "{secs:02d}")
+        fmt = fmt.replace("%i", "{millis:03d}")
+        try:
+            i = fmt.index("%")
+            raise TimeFormatError(
+                "Unknown time format directive '{0}'".format(fmt[i : i + 2])
+            )
+        except ValueError:
+            pass
+
+        def fromatter(seconds):
+            millis = int(seconds * 1000)
+            hrs, millis = divmod(millis, 3600000)
+            mins, millis = divmod(millis, 60000)
+            secs, millis = divmod(millis, 1000)
+            return fmt.format(hrs=hrs, mins=mins, secs=secs, millis=millis)
+
+    return fromatter
+
+
+def make_channel_selector(sample_width, channels, selected=None):
+    """Create and return a callable used for audio channel selection. The
+    returned selector can be used as `selector(audio_data)` and returns data
+    that contains selected channel only.
+
+    Importantly, if `selected` is None or equals "any", `selector(audio_data)`
+    will separate and return a list of available channels:
+    `[data_channe_1, data_channe_2, ...].`
+
+    Note also that returned `selector` expects `bytes` format for input data but
+    does notnecessarily return a `bytes` object. In fact, in order to extract
+    the desired channel (or compute the average channel if `selected` = "avg"),
+    it first converts input data into a `array.array` (or `numpy.ndarray`)
+    object. After channel of interst is selected/computed, it is returned as
+    such, without any reconversion to `bytes`. This behavior is wanted for
+    efficiency purposes because returned objects can be directly used as buffers
+    of bytes. In any case, returned objects can be converted back to `bytes`
+    using `bytes(obj)`.
+
+    Exception to this is the special case where `channels` = 1 in which input
+    data is returned without any processing.
+
+
+    Parameters
+    ----------
+    sample_width : int
+        number of bytes used to encode one audio sample, should be 1, 2 or 4.
+    channels : int
+        number of channels of raw audio data that the returned selector should
+        expect.
+    selected : int or str, default: None
+        audio channel to select and return when calling `selector(raw_data)`. It
+        should be an int >= `-channels` and < `channels`. If one of "mix",
+        "avg" or "average" is passed then `selector` will return the average
+        channel of audio data. If None or "any", return a list of all available
+        channels at each call.
+
+    Returns
+    -------
+    selector : callable
+        a callable that can be used as `selector(audio_data)` and returns data
+        that contains channel of interst.
+
+    Raises
+    ------
+    ValueError
+        if `sample_width` is not one of 1, 2 or 4, or if `selected` has an
+        unexpected value.
     """
-    Base class for objects passed to :func:`auditok.core.StreamTokenizer.tokenize`.
+    fmt = signal.FORMAT.get(sample_width)
+    if fmt is None:
+        err_msg = "'sample_width' must be 1, 2 or 4, given: {}"
+        raise ValueError(err_msg.format(sample_width))
+    if channels == 1:
+        return lambda x: x
+
+    if isinstance(selected, int):
+        if selected < 0:
+            selected += channels
+        if selected < 0 or selected >= channels:
+            err_msg = "Selected channel must be >= -channels and < channels"
+            err_msg += ", given: {}"
+            raise ValueError(err_msg.format(selected))
+        return partial(
+            signal.extract_single_channel,
+            fmt=fmt,
+            channels=channels,
+            selected=selected,
+        )
+
+    if selected in ("mix", "avg", "average"):
+        if channels == 2:
+            # when data is stereo, using audioop when possible is much faster
+            return partial(
+                signal.compute_average_channel_stereo,
+                sample_width=sample_width,
+            )
+
+        return partial(
+            signal.compute_average_channel, fmt=fmt, channels=channels
+        )
+
+    if selected in (None, "any"):
+        return partial(signal.separate_channels, fmt=fmt, channels=channels)
+
+    raise ValueError(
+        "Selected channel must be an integer, None (alias 'any') or 'average' "
+        "(alias 'avg' or 'mix')"
+    )
+
+
+class DataSource(ABC):
+    """
+    Base class for objects passed to :func:`StreamTokenizer.tokenize`.
     Subclasses should implement a :func:`DataSource.read` method.
     """
-    __metaclass__ = ABCMeta
-    
+
     @abstractmethod
     def read(self):
         """
-        Read a piece of data read from this source.
+        Read a block (i.e., window) of data read from this source.
         If no more data is available, return None.
         """
-    
-    
-class DataValidator():
+
+
+class DataValidator(ABC):
     """
-    Base class for a validator object used by :class:`.core.StreamTokenizer` to check
-    if read data is valid.
+    Base class for a validator object used by :class:`.core.StreamTokenizer`
+    to check if read data is valid.
     Subclasses should implement :func:`is_valid` method.
     """
-    __metaclass__ = ABCMeta
-    
+
     @abstractmethod
     def is_valid(self, data):
         """
         Check whether `data` is valid
         """
 
+
+class AudioEnergyValidator(DataValidator):
+    """
+    A validator based on audio signal energy. For an input window of `N` audio
+    samples (see :func:`AudioEnergyValidator.is_valid`), the energy is computed
+    as:
+
+    .. math:: energy = 20 \log(\sqrt({1}/{N}\sum_{i}^{N}{a_i}^2))  % # noqa: W605
+
+    where `a_i` is the i-th audio sample.
+
+    Parameters
+    ----------
+    energy_threshold : float
+        minimum energy that audio window should have to be valid.
+    sample_width : int
+        size in bytes of one audio sample.
+    channels : int
+        number of channels of audio data.
+    use_channel : {None, "any", "mix", "avg", "average"} or int
+        channel to use for energy computation. The following values are
+        accepted:
+
+        - None (alias "any") : compute energy for each of the channels and return
+          the maximum value.
+        - "mix" (alias "avg" or "average") : compute the average channel then
+          compute its energy.
+        - int (>= 0 , < `channels`) : compute the energy of the specified channel
+          and ignore the other ones.
+
+    Returns
+    -------
+    energy : float
+        energy of the audio window.
+    """
+
+    def __init__(
+        self, energy_threshold, sample_width, channels, use_channel=None
+    ):
+        self._sample_width = sample_width
+        self._selector = make_channel_selector(
+            sample_width, channels, use_channel
+        )
+        if channels == 1 or use_channel not in (None, "any"):
+            self._energy_fn = signal.calculate_energy_single_channel
+        else:
+            self._energy_fn = signal.calculate_energy_multichannel
+        self._energy_threshold = energy_threshold
+
+    def is_valid(self, data):
+        """
+
+        Parameters
+        ----------
+        data : bytes-like
+            array of raw audio data
+
+        Returns
+        -------
+        bool
+            True if the energy of audio data is >= threshold, False otherwise.
+        """
+        log_energy = self._energy_fn(self._selector(data), self._sample_width)
+        return log_energy >= self._energy_threshold
+
+
 class StringDataSource(DataSource):
     """
-    A class that represent a :class:`DataSource` as a string buffer.
-    Each call to :func:`DataSource.read` returns on character and moves one step forward.
-    If the end of the buffer is reached, :func:`read` returns None.
-   
-    :Parameters:
-        
-        `data` : 
-            a basestring object.
-     
+    Class that represent a :class:`DataSource` as a string buffer.
+    Each call to :func:`DataSource.read` returns on character and moves one
+    step forward. If the end of the buffer is reached, :func:`read` returns
+    None.
+
+    Parameters
+    ----------
+    data : str
+        a string object used as data.
+
     """
-     
+
     def __init__(self, data):
 
         self._data = None
         self._current = 0
         self.set_data(data)
-        
-    
+
     def read(self):
         """
         Read one character from buffer.
-        
-        :Returns:
-        
-            Current character or None if end of buffer is reached
+
+        Returns
+        -------
+        char : str
+            current character or None if end of buffer is reached.
         """
-        
+
         if self._current >= len(self._data):
             return None
         self._current += 1
         return self._data[self._current - 1]
-    
+
     def set_data(self, data):
         """
         Set a new data buffer.
-        
-        :Parameters:
-        
-            `data` : a basestring object 
-                New data buffer.
+
+        Parameters
+        ----------
+        data : str
+            new data buffer.
         """
-        
-        if not isinstance(data, basestring):
-            raise ValueError("data must an instance of basestring")
+
+        if not isinstance(data, str):
+            raise ValueError("data must an instance of str")
         self._data = data
         self._current = 0
-        
 
 
 class ADSFactory:
     """
-    Factory class that makes it easy to create an :class:`ADSFactory.AudioDataSource` object that implements
-    :class:`DataSource` and can therefore be passed to :func:`auditok.core.StreamTokenizer.tokenize`.
-    
-    Whether you read audio data from a file, the microphone or a memory buffer, this factory
-    instantiates and returns the right :class:`ADSFactory.AudioDataSource` object.
-    
-    There are many other features you want your :class:`ADSFactory.AudioDataSource` object to have, such as: 
-    memorize all read audio data so that you can rewind and reuse it (especially useful when 
-    reading data from the microphone), read a fixed amount of data (also useful when reading 
-    from the microphone), read overlapping audio frames (often needed when dosing a spectral
-    analysis of data).
-    
-    :func:`ADSFactory.ads` automatically creates and return object with the desired behavior according
-    to the supplied keyword arguments. 
-     
+    .. deprecated:: 2.0.0
+          `ADSFactory` will be removed in auditok 2.0.1, use instances of
+          :class:`AudioReader` instead.
+
+    Factory class that makes it easy to create an
+    :class:`AudioDataSource` object that implements
+    :class:`DataSource` and can therefore be passed to
+    :func:`auditok.core.StreamTokenizer.tokenize`.
+
+    Whether you read audio data from a file, the microphone or a memory buffer,
+    this factory instantiates and returns the right
+    :class:`AudioDataSource` object.
+
+    There are many other features you want a :class:`AudioDataSource` object to
+    have, such as: memorize all read audio data so that you can rewind and reuse
+    it (especially useful when reading data from the microphone), read a fixed
+    amount of data (also useful when reading from the microphone), read
+    overlapping audio frames (often needed when dosing a spectral analysis of
+    data).
+
+    :func:`ADSFactory.ads` automatically creates and return object with the
+    desired behavior according to the supplied keyword arguments.
     """
-    
-    @staticmethod
+
+    @staticmethod  # noqa: C901
     def _check_normalize_args(kwargs):
-        
+
         for k in kwargs:
-            if not k in ["block_dur", "hop_dur", "block_size", "hop_size", "max_time", "record",
-                         "audio_source", "filename", "data_buffer", "frames_per_buffer", "sampling_rate",
-                         "sample_width", "channels", "sr", "sw", "ch", "asrc", "fn", "fpb", "db", "mt",
-                         "rec", "bd", "hd", "bs", "hs"]:
+            if k not in [
+                "block_dur",
+                "hop_dur",
+                "block_size",
+                "hop_size",
+                "max_time",
+                "record",
+                "audio_source",
+                "filename",
+                "data_buffer",
+                "frames_per_buffer",
+                "sampling_rate",
+                "sample_width",
+                "channels",
+                "sr",
+                "sw",
+                "ch",
+                "asrc",
+                "fn",
+                "fpb",
+                "db",
+                "mt",
+                "rec",
+                "bd",
+                "hd",
+                "bs",
+                "hs",
+            ]:
                 raise ValueError("Invalid argument: {0}".format(k))
-        
+
         if "block_dur" in kwargs and "bd" in kwargs:
-            raise DuplicateArgument("Either 'block_dur' or 'bd' must be specified, not both")
-        
+            raise DuplicateArgument(
+                "Either 'block_dur' or 'bd' must be specified, not both"
+            )
+
         if "hop_dur" in kwargs and "hd" in kwargs:
-            raise DuplicateArgument("Either 'hop_dur' or 'hd' must be specified, not both")
-        
+            raise DuplicateArgument(
+                "Either 'hop_dur' or 'hd' must be specified, not both"
+            )
+
         if "block_size" in kwargs and "bs" in kwargs:
-            raise DuplicateArgument("Either 'block_size' or 'bs' must be specified, not both")
-        
+            raise DuplicateArgument(
+                "Either 'block_size' or 'bs' must be specified, not both"
+            )
+
         if "hop_size" in kwargs and "hs" in kwargs:
-            raise DuplicateArgument("Either 'hop_size' or 'hs' must be specified, not both")
-        
+            raise DuplicateArgument(
+                "Either 'hop_size' or 'hs' must be specified, not both"
+            )
+
         if "max_time" in kwargs and "mt" in kwargs:
-            raise DuplicateArgument("Either 'max_time' or 'mt' must be specified, not both")
-        
+            raise DuplicateArgument(
+                "Either 'max_time' or 'mt' must be specified, not both"
+            )
+
         if "audio_source" in kwargs and "asrc" in kwargs:
-            raise DuplicateArgument("Either 'audio_source' or 'asrc' must be specified, not both")
-        
+            raise DuplicateArgument(
+                "Either 'audio_source' or 'asrc' must be specified, not both"
+            )
+
         if "filename" in kwargs and "fn" in kwargs:
-            raise DuplicateArgument("Either 'filename' or 'fn' must be specified, not both")
-        
+            raise DuplicateArgument(
+                "Either 'filename' or 'fn' must be specified, not both"
+            )
+
         if "data_buffer" in kwargs and "db" in kwargs:
-            raise DuplicateArgument("Either 'filename' or 'db' must be specified, not both")
-        
+            raise DuplicateArgument(
+                "Either 'filename' or 'db' must be specified, not both"
+            )
+
         if "frames_per_buffer" in kwargs and "fbb" in kwargs:
-            raise DuplicateArgument("Either 'frames_per_buffer' or 'fpb' must be specified, not both")
-        
+            raise DuplicateArgument(
+                "Either 'frames_per_buffer' or 'fpb' must be specified, not "
+                "both"
+            )
+
         if "sampling_rate" in kwargs and "sr" in kwargs:
-            raise DuplicateArgument("Either 'sampling_rate' or 'sr' must be specified, not both")
-        
+            raise DuplicateArgument(
+                "Either 'sampling_rate' or 'sr' must be specified, not both"
+            )
+
         if "sample_width" in kwargs and "sw" in kwargs:
-            raise DuplicateArgument("Either 'sample_width' or 'sw' must be specified, not both")
-        
+            raise DuplicateArgument(
+                "Either 'sample_width' or 'sw' must be specified, not both"
+            )
+
         if "channels" in kwargs and "ch" in kwargs:
-            raise DuplicateArgument("Either 'channels' or 'ch' must be specified, not both")
-        
+            raise DuplicateArgument(
+                "Either 'channels' or 'ch' must be specified, not both"
+            )
+
         if "record" in kwargs and "rec" in kwargs:
-            raise DuplicateArgument("Either 'record' or 'rec' must be specified, not both")
-        
-        
+            raise DuplicateArgument(
+                "Either 'record' or 'rec' must be specified, not both"
+            )
+
         kwargs["bd"] = kwargs.pop("block_dur", None) or kwargs.pop("bd", None)
         kwargs["hd"] = kwargs.pop("hop_dur", None) or kwargs.pop("hd", None)
         kwargs["bs"] = kwargs.pop("block_size", None) or kwargs.pop("bs", None)
         kwargs["hs"] = kwargs.pop("hop_size", None) or kwargs.pop("hs", None)
         kwargs["mt"] = kwargs.pop("max_time", None) or kwargs.pop("mt", None)
-        kwargs["asrc"] = kwargs.pop("audio_source", None) or kwargs.pop("asrc", None)
+        kwargs["asrc"] = kwargs.pop("audio_source", None) or kwargs.pop(
+            "asrc", None
+        )
         kwargs["fn"] = kwargs.pop("filename", None) or kwargs.pop("fn", None)
         kwargs["db"] = kwargs.pop("data_buffer", None) or kwargs.pop("db", None)
-        
+
         record = kwargs.pop("record", False)
         if not record:
             record = kwargs.pop("rec", False)
             if not isinstance(record, bool):
                 raise TypeError("'record' must be a boolean")
-            
+
         kwargs["rec"] = record
-        
-        # keep long names for arguments meant for BufferAudioSource and PyAudioSource
+
+        # keep long names for arguments meant for BufferAudioSource
+        # and PyAudioSource
         if "frames_per_buffer" in kwargs or "fpb" in kwargs:
-            kwargs["frames_per_buffer"] = kwargs.pop("frames_per_buffer", None) or kwargs.pop("fpb", None)
-        
+            kwargs["frames_per_buffer"] = kwargs.pop(
+                "frames_per_buffer", None
+            ) or kwargs.pop("fpb", None)
+
         if "sampling_rate" in kwargs or "sr" in kwargs:
-            kwargs["sampling_rate"] = kwargs.pop("sampling_rate", None) or kwargs.pop("sr", None)
-        
-        if "sample_width" in kwargs or "sw" in kwargs:    
-            kwargs["sample_width"] = kwargs.pop("sample_width", None) or kwargs.pop("sw", None)
-        
+            kwargs["sampling_rate"] = kwargs.pop(
+                "sampling_rate", None
+            ) or kwargs.pop("sr", None)
+
+        if "sample_width" in kwargs or "sw" in kwargs:
+            kwargs["sample_width"] = kwargs.pop(
+                "sample_width", None
+            ) or kwargs.pop("sw", None)
+
         if "channels" in kwargs or "ch" in kwargs:
-            kwargs["channels"] = kwargs.pop("channels", None) or kwargs.pop("ch", None)
-        
-        
-        
-        
-            
-            
-    
+            kwargs["channels"] = kwargs.pop("channels", None) or kwargs.pop(
+                "ch", None
+            )
+
     @staticmethod
     def ads(**kwargs):
-        
         """
-        Create an return an :class:`ADSFactory.AudioDataSource`. The type and behavior of the object is the result
-        of the supplied parameters.
-        
-        :Parameters:
-        
-        *No parameters* :  
-           read audio data from the available built-in microphone with the default parameters.
-           The returned :class:`ADSFactory.AudioDataSource` encapsulate an :class:`io.PyAudioSource` object and hence 
-           it accepts the next four parameters are passed to use instead of their default values.
-        
-        `sampling_rate`, `sr` : *(int)*
-            number of samples per second. Default = 16000.
-        
-        `sample_width`, `sw` : *(int)*
-            number of bytes per sample (must be in (1, 2, 4)). Default = 2
-        
-        `channels`, `ch` : *(int)*
-            number of audio channels. Default = 1 (only this value is currently accepted)  
-            
-        `frames_per_buffer`, `fpb` : *(int)*
-            number of samples of PyAudio buffer. Default = 1024.
-        
-        `audio_source`, `asrc` : an `AudioSource` object
-            read data from this audio source
-            
-        `filename`, `fn` : *(string)*
-            build an `io.AudioSource` object using this file (currently only wave format is supported)
-            
-        `data_buffer`, `db` : *(string)*
-            build an `io.BufferAudioSource` using data in `data_buffer`. If this keyword is used,
-            `sampling_rate`, `sample_width` and `channels` are passed to `io.BufferAudioSource`
-            constructor and used instead of default values.
-            
-        `max_time`, `mt` : *(float)*
-            maximum time (in seconds) to read. Default behavior: read until there is no more data
-            available. 
-         
-        `record`, `rec` : *(bool)*
-            save all read data in cache. Provide a navigable object which boasts a `rewind` method.
-            Default = False.
-        
-        `block_dur`, `bd` : *(float)*
-            processing block duration in seconds. This represents the quantity of audio data to return 
-            each time the :func:`read` method is invoked. If `block_dur` is 0.025 (i.e. 25 ms) and the sampling
-            rate is 8000 and the sample width is 2 bytes, :func:`read` returns a buffer of 0.025 * 8000 * 2 = 400
-            bytes at most. This parameter will be looked for (and used if available) before `block_size`.
-            If neither parameter is given, `block_dur` will be set to 0.01 second (i.e. 10 ms)
-            
-            
-        `hop_dur`, `hd` : *(float)*
-            quantity of data to skip from current processing window. if `hop_dur` is supplied then there
-            will be an overlap of `block_dur` - `hop_dur` between two adjacent blocks. This
-            parameter will be looked for (and used if available) before `hop_size`. If neither parameter
-            is given, `hop_dur` will be set to `block_dur` which means that there will be no overlap
-            between two consecutively read blocks.
-             
-        `block_size`, `bs` : *(int)*
-            number of samples to read each time the `read` method is called. Default: a block size
-            that represents a window of 10ms, so for a sampling rate of 16000, the default `block_size`
-            is 160 samples, for a rate of 44100, `block_size` = 441 samples, etc.
-        
-        `hop_size`, `hs` : *(int)*
-            determines the number of overlapping samples between two adjacent read windows. For a
-            `hop_size` of value *N*, the overlap is `block_size` - *N*. Default : `hop_size` = `block_size`,
-            means that there is no overlap.
-            
-        :Returns:
-        
-        An AudioDataSource object that has the desired features.
-        
-        :Exampels:
-        
-        1. **Create an AudioDataSource that reads data from the microphone (requires Pyaudio) with default audio parameters:**
-        
-        .. code:: python
-        
-            from auditok import ADSFactory
-            ads = ADSFactory.ads()
-            ads.get_sampling_rate()
-            16000
-            ads.get_sample_width()
-            2
-            ads.get_channels()
-            1
-        
-        
-        2. **Create an AudioDataSource that reads data from the microphone with a sampling rate of 48KHz:**
-        
-        .. code:: python
-        
-            from auditok import ADSFactory
-            ads = ADSFactory.ads(sr=48000)
-            ads.get_sampling_rate()
-            48000
-        
-        3. **Create an AudioDataSource that reads data from a wave file:**
-        
-        .. code:: python
-        
-            import auditok
-            from auditok import ADSFactory
-            ads = ADSFactory.ads(fn=auditok.dataset.was_der_mensch_saet_mono_44100_lead_trail_silence)
-            ads.get_sampling_rate()
-            44100
-            ads.get_sample_width()
-            2
-            ads.get_channels()
-            1
-        
-        4. **Define size of read blocks as 20 ms**
-        
-        .. code:: python
-        
-            import auditok
-            from auditok import ADSFactory
-            '''
-            we know samling rate for previous file is 44100 samples/second
-            so 10 ms are equivalent to 441 samples and 20 ms to 882
-            '''
-            block_size = 882
-            ads = ADSFactory.ads(bs = 882, fn=auditok.dataset.was_der_mensch_saet_mono_44100_lead_trail_silence)
-            ads.open()
-            # read one block
-            data = ads.read()
-            ads.close()
-            len(data)
-            1764
-            assert len(data) ==  ads.get_sample_width() * block_size
-        
-        5. **Define block size as a duration (use block_dur or bd):**
-        
-        .. code:: python
-        
-            import auditok
-            from auditok import ADSFactory
-            dur = 0.25 # second
-            ads = ADSFactory.ads(bd = dur, fn=auditok.dataset.was_der_mensch_saet_mono_44100_lead_trail_silence)
-            '''
-            we know samling rate for previous file is 44100 samples/second
-            for a block duration of 250 ms, block size should be 0.25 * 44100 = 11025
-            '''
-            ads.get_block_size()
-            11025
-            assert ads.get_block_size() ==  int(0.25 * 44100)
-            ads.open()
-            # read one block
-            data = ads.read()
-            ads.close()
-            len(data)
-            22050
-            assert len(data) ==  ads.get_sample_width() * ads.get_block_size()
-            
-        6. **Read overlapping blocks (one of hope_size, hs, hop_dur or hd > 0):**
-        
-        For better readability we'd better use :class:`auditok.io.BufferAudioSource` with a string buffer:
-
-        .. code:: python
-
-            import auditok
-            from auditok import ADSFactory
-            '''
-            we supply a data beffer instead of a file (keyword 'bata_buffer' or 'db')
-            sr : sampling rate = 16 samples/sec
-            sw : sample width = 1 byte
-            ch : channels = 1
-            '''
-            buffer = "abcdefghijklmnop" # 16 bytes = 1 second of data
-            bd = 0.250 # block duration = 250 ms = 4 bytes
-            hd = 0.125 # hop duration = 125 ms = 2 bytes 
-            ads = ADSFactory.ads(db = "abcdefghijklmnop", bd = bd, hd = hd, sr = 16, sw = 1, ch = 1)
-            ads.open()
-            ads.read()
-            'abcd'
-            ads.read()
-            'cdef'
-            ads.read()
-            'efgh'
-            ads.read()
-            'ghij'
-            data = ads.read()
-            assert data == 'ijkl'
-        
-        7. **Limit amount of read data (use max_time or mt):**
-        
-        .. code:: python
-        
-            '''
-            We know audio file is larger than 2.25 seconds
-            We want to read up to 2.25 seconds of audio data
-            '''
-            ads = ADSFactory.ads(mt = 2.25, fn=auditok.dataset.was_der_mensch_saet_mono_44100_lead_trail_silence)
-            ads.open()
-            data = []
-            while True:
-                d = ads.read()
-                if d is None:
-                    break
-                data.append(d)
-                
-            ads.close()
-            data = b''.join(data)
-            assert len(data) == int(ads.get_sampling_rate() * 2.25 * ads.get_sample_width() * ads.get_channels())
+        Create an return an :class:`AudioDataSource`. The type and
+        behavior of the object is the result
+        of the supplied parameters. Called without any parameters, the class
+        will read audio data from the available built-in microphone with the
+        default parameters.
+
+        Parameters
+        ----------
+        sampling_rate, sr : int, default: 16000
+            number of audio samples per second of input audio stream.
+        sample_width, sw : int, default: 2
+            number of bytes per sample, must be one of 1, 2 or 4
+        channels, ch : int, default: 1
+            number of audio channels, only a value of 1 is currently accepted.
+        frames_per_buffer, fpb : int, default: 1024
+            number of samples of PyAudio buffer.
+        audio_source, asrc : `AudioSource`
+            `AudioSource` to read data from
+        filename, fn : str
+            create an `AudioSource` object using this file
+        data_buffer, db : str
+            build an `io.BufferAudioSource` using data in `data_buffer`.
+            If this keyword is used,
+            `sampling_rate`, `sample_width` and `channels` are passed to
+            `io.BufferAudioSource` constructor and used instead of default
+            values.
+        max_time, mt : float
+            maximum time (in seconds) to read. Default behavior: read until
+            there is no more data
+            available.
+        record, rec : bool, default = False
+            save all read data in cache. Provide a navigable object which has a
+            `rewind` method.
+        block_dur, bd : float
+            processing block duration in seconds. This represents the quantity
+            of audio data to return each time the :func:`read` method is
+            invoked. If `block_dur` is 0.025 (i.e. 25 ms) and the sampling rate
+            is 8000 and the sample width is 2 bytes, :func:`read` returns a
+            buffer of 0.025 * 8000 * 2 = 400 bytes at most. This parameter will
+            be looked for (and used if available) before `block_size`. If
+            neither parameter is given, `block_dur` will be set to 0.01 second
+            (i.e. 10 ms)
+        hop_dur, hd : float
+            quantity of data to skip from current processing window. if
+            `hop_dur` is supplied then there will be an overlap of `block_dur`
+            - `hop_dur` between two adjacent blocks. This parameter will be
+            looked for (and used if available) before `hop_size`.
+            If neither parameter is given, `hop_dur` will be set to `block_dur`
+            which means that there will be no overlap between two consecutively
+            read blocks.
+        block_size, bs : int
+            number of samples to read each time the `read` method is called.
+            Default: a block size that represents a window of 10ms, so for a
+            sampling rate of 16000, the default `block_size` is 160 samples,
+            for a rate of 44100, `block_size` = 441 samples, etc.
+        hop_size, hs : int
+            determines the number of overlapping samples between two adjacent
+            read windows. For a `hop_size` of value *N*, the overlap is
+            `block_size` - *N*. Default : `hop_size` = `block_size`, means that
+            there is no overlap.
+
+        Returns
+        -------
+        audio_data_source : AudioDataSource
+            an `AudioDataSource` object build with input parameters.
         """
-        
-        # copy user's dicionary (shallow copy)
-        kwargs = kwargs.copy()
-        
+        warnings.warn(
+            "'ADSFactory' is deprecated and will be removed in a future "
+            "release. Please use AudioReader class instead.",
+            DeprecationWarning,
+        )
+
         # check and normalize keyword arguments
         ADSFactory._check_normalize_args(kwargs)
-        
+
         block_dur = kwargs.pop("bd")
         hop_dur = kwargs.pop("hd")
         block_size = kwargs.pop("bs")
@@ -452,431 +628,483 @@ class ADSFactory:
         filename = kwargs.pop("fn")
         data_buffer = kwargs.pop("db")
         record = kwargs.pop("rec")
-        
+
         # Case 1: an audio source is supplied
         if audio_source is not None:
             if (filename, data_buffer) != (None, None):
-                raise Warning("You should provide one of 'audio_source', 'filename' or 'data_buffer'\
-                 keyword parameters. 'audio_source' will be used")
-            
+                raise Warning(
+                    "You should provide one of 'audio_source', 'filename' or \
+                    'data_buffer' keyword parameters. 'audio_source' will be \
+                    used"
+                )
+
         # Case 2: a file name is supplied
         elif filename is not None:
             if data_buffer is not None:
-                raise Warning("You should provide one of 'filename' or 'data_buffer'\
-                 keyword parameters. 'filename' will be used")
+                raise Warning(
+                    "You should provide one of 'filename' or 'data_buffer'\
+                 keyword parameters. 'filename' will be used"
+                )
             audio_source = from_file(filename)
-            
-        # Case 3: a data_buffer is supplied 
+
+        # Case 3: a data_buffer is supplied
         elif data_buffer is not None:
-            audio_source = BufferAudioSource(data_buffer = data_buffer, **kwargs)
-            
+            audio_source = BufferAudioSource(data=data_buffer, **kwargs)
+
         # Case 4: try to access native audio input
         else:
             audio_source = PyAudioSource(**kwargs)
-             
-             
+
         if block_dur is not None:
             if block_size is not None:
-                raise DuplicateArgument("Either 'block_dur' or 'block_size' can be specified, not both")
-            else:
-                block_size = int(audio_source.get_sampling_rate() * block_dur)
-        elif block_size is None:
-            # Set default block_size to 10 ms
-            block_size = int(audio_source.get_sampling_rate() / 100)
-
-        # Instantiate base AudioDataSource  
-        ads = ADSFactory.AudioDataSource(audio_source=audio_source, block_size=block_size)
-        
-        # Limit data to be read
-        if max_time is not None:
-            ads = ADSFactory.LimiterADS(ads=ads, max_time=max_time)
-        
-        # Record, rewind and reuse data
-        if record:
-            ads = ADSFactory.RecorderADS(ads=ads)
-            
+                raise DuplicateArgument(
+                    "Either 'block_dur' or 'block_size' can be specified, not \
+                    both"
+                )
+        elif block_size is not None:
+            block_dur = block_size / audio_source.sr
+        else:
+            block_dur = 0.01  # 10 ms
+
         # Read overlapping blocks of data
         if hop_dur is not None:
             if hop_size is not None:
-                raise DuplicateArgument("Either 'hop_dur' or 'hop_size' can be specified, not both")
-            else:
-                hop_size = int(audio_source.get_sampling_rate() * hop_dur)
-            
-        if hop_size is not None:
-            if hop_size <= 0 or  hop_size > block_size:
-                raise ValueError("hop_size must be > 0 and <= block_size")
-            if hop_size < block_size:
-                ads = ADSFactory.OverlapADS(ads=ads, hop_size=hop_size)
-        
+                raise DuplicateArgument(
+                    "Either 'hop_dur' or 'hop_size' can be specified, not both"
+                )
+        elif hop_size is not None:
+            hop_dur = hop_size / audio_source.sr
+
+        ads = AudioDataSource(
+            audio_source,
+            block_dur=block_dur,
+            hop_dur=hop_dur,
+            record=record,
+            max_read=max_time,
+        )
         return ads
-        
-        
-    class AudioDataSource(DataSource):
-        """
-        Base class for AudioDataSource objects.
-        It inherits from DataSource and encapsulates an AudioSource object.
-        """
-        
-        def __init__(self, audio_source, block_size):
-            
-            self.audio_source = audio_source
-            self.block_size = block_size
-                
-        def get_block_size(self):
-            return self.block_size
-        
-        def set_block_size(self, size):
-            self.block_size = size
-
-        def get_audio_source(self):
-            return self.audio_source
-        
-        def set_audio_source(self, audio_source):
-            self.audio_source = audio_source
-            
-        def open(self):
-            self.audio_source.open()
-        
-        def close(self):
-            self.audio_source.close()
-            
-        def is_open(self):
-            return self.audio_source.is_open()
-        
-        def get_sampling_rate(self):
-            return self.audio_source.get_sampling_rate()
-        
-        def get_sample_width(self):
-            return self.audio_source.get_sample_width()
-        
-        def get_channels(self):
-            return self.audio_source.get_channels()
-        
-        
-        def rewind(self):
-            if isinstance(self.audio_source, Rewindable):
-                self.audio_source.rewind()
-            else:
-                raise Exception("Audio source is not rewindable")
-            
-            
-        
-        def is_rewindable(self):
-            return isinstance(self.audio_source, Rewindable)
-        
-            
-        def read(self):
-            return self.audio_source.read(self.block_size)
-
-
-    class ADSDecorator(AudioDataSource):
-        """
-        Base decorator class for AudioDataSource objects.
-        """
-        __metaclass__ = ABCMeta
-        
-        def __init__(self, ads):
-            self.ads = ads
-            
-            self.get_block_size = self.ads.get_block_size
-            self.set_block_size = self.ads.set_block_size
-            self.get_audio_source = self.ads.get_audio_source
-            self.open = self.ads.open
-            self.close = self.ads.close
-            self.is_open = self.ads.is_open
-            self.get_sampling_rate = self.ads.get_sampling_rate
-            self.get_sample_width = self.ads.get_sample_width
-            self.get_channels = self.ads.get_channels
-        
-        def is_rewindable(self):
-            return self.ads.is_rewindable
-            
-        def rewind(self):
-            self.ads.rewind()
-            self._reinit()
-            
-        def set_audio_source(self, audio_source):
-            self.ads.set_audio_source(audio_source)
-            self._reinit()
-        
-        def open(self):
-            if not self.ads.is_open():
-                self.ads.open()
-                self._reinit()
-            
-        @abstractmethod
-        def _reinit(self):
-            pass            
-        
-        
-    class OverlapADS(ADSDecorator):
-        """
-        A class for AudioDataSource objects that can read and return overlapping audio frames
-        """
-        
-        def __init__(self, ads, hop_size):
-            ADSFactory.ADSDecorator.__init__(self, ads)
-            
-            if hop_size <= 0 or hop_size > self.get_block_size():
-                raise ValueError("hop_size must be either 'None' or \
-                 between 1 and block_size (both inclusive)")
-            self.hop_size = hop_size
-            self._actual_block_size = self.get_block_size()
-            self._reinit()
-            
-            
-            def _get_block_size():
-                return self._actual_block_size
-            
-            
-        def _read_first_block(self):
-            # For the first call, we need an entire block of size 'block_size'
-            block = self.ads.read()
-            if block is None:
-                return None
-            
-            # Keep a slice of data in cache and append it in the next call
-            if len(block) > self._hop_size_bytes:
-                self._cache = block[self._hop_size_bytes:]
-            
-            # Up from the next call, we will use '_read_next_blocks'
-            # and we only read 'hop_size'
-            self.ads.set_block_size(self.hop_size)
-            self.read = self._read_next_blocks
-            
-            return block
-                
-        def _read_next_blocks(self):
-            block = self.ads.read()
-            if block is None:
-                return None
-            
-            # Append block to cache data to ensure overlap
-            block = self._cache + block
-            # Keep a slice of data in cache only if we have a full length block
-            # if we don't that means that this is the last block
-            if len(block) == self._block_size_bytes:
-                self._cache = block[self._hop_size_bytes:]
-            else:
-                self._cache = None
-                
-            return block
 
-        def read(self):
-            pass
-        
-        def _reinit(self):
+
+class _AudioReadingProxy:
+    def __init__(self, audio_source):
+
+        self._audio_source = audio_source
+
+    def rewind(self):
+        if self.rewindable:
+            self._audio_source.rewind()
+        else:
+            raise AudioIOError("Audio stream is not rewindable")
+
+    def rewindable(self):
+        try:
+            return self._audio_source.rewindable
+        except AttributeError:
+            return False
+
+    def is_open(self):
+        return self._audio_source.is_open()
+
+    def open(self):
+        self._audio_source.open()
+
+    def close(self):
+        self._audio_source.close()
+
+    def read(self, size):
+        return self._audio_source.read(size)
+
+    @property
+    def data(self):
+        err_msg = "This AudioReader is not a recorder, no recorded data can "
+        err_msg += "be retrieved"
+        raise AttributeError(err_msg)
+
+    def __getattr__(self, name):
+        return getattr(self._audio_source, name)
+
+
+class _Recorder(_AudioReadingProxy):
+    """
+    Class for `AudioReader` objects that can record all data they read. Useful
+    when reading data from microphone.
+    """
+
+    def __init__(self, audio_source):
+        super(_Recorder, self).__init__(audio_source)
+        self._cache = []
+        self._read_block = self._read_and_cache
+        self._read_from_cache = False
+        self._data = None
+
+    def read(self, size):
+        return self._read_block(size)
+
+    @property
+    def data(self):
+        if self._data is None:
+            err_msg = "Unrewinded recorder. `rewind` should be called before "
+            err_msg += "accessing recorded data"
+            raise RuntimeError(err_msg)
+        return self._data
+
+    def rewindable(self):
+        return True
+
+    def rewind(self):
+        if self._read_from_cache:
+            self._audio_source.rewind()
+        else:
+            self._data = b"".join(self._cache)
             self._cache = None
-            self.ads.set_block_size(self._actual_block_size)
-            self._hop_size_bytes = self.hop_size * \
-                               self.get_sample_width() * \
-                               self.get_channels()
-            self._block_size_bytes = self.get_block_size() * \
-                               self.get_sample_width() * \
-                               self.get_channels()
-            self.read = self._read_first_block
+            self._audio_source = BufferAudioSource(
+                self._data, self.sr, self.sw, self.ch
+            )
+            self._read_block = self._audio_source.read
+            self.open()
+            self._read_from_cache = True
 
+    def _read_and_cache(self, size):
+        # Read and save read data
+        block = self._audio_source.read(size)
+        if block is not None:
+            self._cache.append(block)
+        return block
 
 
-    class LimiterADS(ADSDecorator):
-        """
-        A class for AudioDataSource objects that can read a fixed amount of data.
-        This can be useful when reading data from the microphone or from large audio files.
-        """
-        
-        def __init__(self, ads, max_time):
-            ADSFactory.ADSDecorator.__init__(self, ads)
-            
-            self.max_time = max_time
-            self._reinit()
-            
-        def read(self):
-            if self._total_read_bytes >=  self._max_read_bytes:
-                return None
-            block = self.ads.read()
-            if block is None:
-                return None
-            self._total_read_bytes += len(block)
-            
-            if self._total_read_bytes >=  self._max_read_bytes:
-                self.close()
-            
-            return block
-                
-                
-        def _reinit(self):
-            self._max_read_bytes = int(self.max_time  * self.get_sampling_rate()) * \
-                                  self.get_sample_width() * \
-                                  self.get_channels()
-            self._total_read_bytes = 0
+class _Limiter(_AudioReadingProxy):
+    """
+    Class for `AudioReader` objects that can read a fixed amount of data.
+    This can be useful when reading data from the microphone or from large
+    audio files.
+    """
 
-            
+    def __init__(self, audio_source, max_read):
+        super(_Limiter, self).__init__(audio_source)
+        self._max_read = max_read
+        self._max_samples = round(max_read * self.sr)
+        self._bytes_per_sample = self.sw * self.ch
+        self._read_samples = 0
 
-    class RecorderADS(ADSDecorator):
-        """
-        A class for AudioDataSource objects that can record all audio data they read,
-        with a rewind facility.
-        """
-        
-        def __init__(self, ads):
-            ADSFactory.ADSDecorator.__init__(self, ads)
-            
-            self._reinit()
-            
-        def read(self):
-            pass
-        
-        def _read_and_rec(self):
-            # Read and save read data
-            block = self.ads.read()
-            if block is not None:
-                self._cache.append(block)
-            
+    @property
+    def data(self):
+        data = self._audio_source.data
+        max_read_bytes = self._max_samples * self._bytes_per_sample
+        return data[:max_read_bytes]
+
+    @property
+    def max_read(self):
+        return self._max_read
+
+    def read(self, size):
+        size = min(self._max_samples - self._read_samples, size)
+        if size <= 0:
+            return None
+        block = self._audio_source.read(size)
+        if block is None:
+            return None
+        self._read_samples += len(block) // self._bytes_per_sample
+        return block
+
+    def rewind(self):
+        super(_Limiter, self).rewind()
+        self._read_samples = 0
+
+
+class _FixedSizeAudioReader(_AudioReadingProxy):
+    """
+    Class to read fixed-size audio windows from source.
+    """
+
+    def __init__(self, audio_source, block_dur):
+        super(_FixedSizeAudioReader, self).__init__(audio_source)
+
+        if block_dur <= 0:
+            raise ValueError(
+                "block_dur must be > 0, given: {}".format(block_dur)
+            )
+
+        self._block_size = int(block_dur * self.sr)
+        if self._block_size == 0:
+            err_msg = "Too small block_dur ({0:f}) for sampling rate ({1}). "
+            err_msg += "block_dur should cover at least one sample "
+            err_msg += "(i.e. 1/{1})"
+            raise TooSamllBlockDuration(
+                err_msg.format(block_dur, self.sr), block_dur, self.sr
+            )
+
+    def read(self):
+        return self._audio_source.read(self._block_size)
+
+    @property
+    def block_size(self):
+        return self._block_size
+
+    @property
+    def block_dur(self):
+        return self._block_size / self.sr
+
+    def __getattr__(self, name):
+        return getattr(self._audio_source, name)
+
+
+class _OverlapAudioReader(_FixedSizeAudioReader):
+    """
+    Class for `AudioReader` objects that can read and return overlapping audio
+    windows.
+    """
+
+    def __init__(self, audio_source, block_dur, hop_dur):
+
+        if hop_dur >= block_dur:
+            raise ValueError('"hop_dur" should be < "block_dur"')
+
+        super(_OverlapAudioReader, self).__init__(audio_source, block_dur)
+
+        self._hop_size = int(hop_dur * self.sr)
+        self._blocks = self._iter_blocks_with_overlap()
+
+    def _iter_blocks_with_overlap(self):
+        while not self.is_open():
+            yield AudioIOError
+        block = self._audio_source.read(self._block_size)
+        if block is None:
+            yield None
+
+        _hop_size_bytes = (
+            self._hop_size * self._audio_source.sw * self._audio_source.ch
+        )
+        cache = block[_hop_size_bytes:]
+        yield block
+
+        while True:
+            block = self._audio_source.read(self._hop_size)
+            if block:
+                block = cache + block
+                cache = block[_hop_size_bytes:]
+                yield block
+                continue
+            yield None
+
+    def read(self):
+        try:
+            block = next(self._blocks)
+            if block == AudioIOError:
+                raise AudioIOError("Audio Stream is not open.")
             return block
-            
-            
-        def _read_simple(self):
-            # Read without recording
-            return self.ads.read()
-
-        def rewind(self):
-            if self._record:
-                # If has been recording, create a new BufferAudioSource
-                # from recorded data
-                dbuffer = self._concatenate(self._cache)
-                asource = BufferAudioSource(dbuffer, self.get_sampling_rate(),
-                                             self.get_sample_width(),
-                                             self.get_channels())
-                
-                
-                self.set_audio_source(asource)
-                self.open()
-                self._cache = []
-                self._record = False
-                self.read = self._read_simple
-            
-            else:
-                self.ads.rewind()
-                if not self.is_open():
-                    self.open()
-                    
-        
-        def is_rewindable(self):
-            return True
-        
-        def _reinit(self):
-            # when audio_source is replaced, start recording again
-            self._record = True
-            self._cache = []
-            self.read = self._read_and_rec
-        
-        def _concatenate(self, data):
-            try:
-                # should always work for python 2
-                # work for python 3 ONLY if data is a list (or an iterator)
-                # whose each element is a 'bytes' objects
-                return b''.join(data)
-            except TypeError:
-                # work for 'str' in python 2 and python 3
-                return ''.join(data)
+        except StopIteration:
+            return None
 
+    def rewind(self):
+        super(_OverlapAudioReader, self).rewind()
+        self._blocks = self._iter_blocks_with_overlap()
 
-class AudioEnergyValidator(DataValidator):
+    @property
+    def hop_size(self):
+        return self._hop_size
+
+    @property
+    def hop_dur(self):
+        return self._hop_size / self.sr
+
+    def __getattr__(self, name):
+        return getattr(self._audio_source, name)
+
+
+class AudioReader(DataSource):
     """
-    The most basic auditok audio frame validator.
-    This validator computes the log energy of an input audio frame
-    and return True if the result is >= a given threshold, False 
-    otherwise.
-    
-    :Parameters:
-    
-    `sample_width` : *(int)*
-        Number of bytes of one audio sample. This is used to convert data from `basestring` or `Bytes` to
-        an array of floats.
-        
-    `energy_threshold` : *(float)*
-        A threshold used to check whether an input data buffer is valid.
+    Class to read fixed-size chunks of audio data from a source. A source can
+    be a file on disk, standard input (with `input` = "-") or microphone. This
+    is normally used by tokenization algorithms that expect source objects with
+    a `read` function that returns a windows of data of the same size at each
+    call expect when remaining data does not make up a full window.
+
+    Objects of this class can be set up to return audio windows with a given
+    overlap and to record the whole stream for later access (useful when
+    reading data from the microphone). They can also have
+    a limit for the maximum amount of data to read.
+
+    Parameters
+    ----------
+    input : str, bytes, AudioSource, AudioReader, AudioRegion or None
+        input audio data. If the type of the passed argument is `str`, it should
+        be a path to an existing audio file. "-" is interpreted as standardinput.
+        If the type is `bytes`, input is considered as a buffer of raw audio
+        data. If None, read audio from microphone. Every object that is not an
+        :class:`AudioReader` will be transformed, when possible, into an
+        :class:`AudioSource` 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).
+    block_dur: float, default: 0.01
+        length in seconds of audio windows to return at each `read` call.
+    hop_dur: float, default: None
+        length in seconds of data amount to skip from previous window. If
+        defined, it is used to compute the temporal overlap between previous and
+        current window (nameply `overlap = block_dur - hop_dur`). Default, None,
+        means that consecutive windows do not overlap.
+    record: bool, default: False
+        whether to record read audio data for later access. If True, audio data
+        can be retrieved by first calling `rewind()`, then using the `data`
+        property. Note that once `rewind()` is called, no new data will be read
+        from source (subsequent `read()` call will read data from cache) and
+        that there's no need to call `rewind()` again to access `data` property.
+    max_read: float, default: None
+        maximum amount of audio data to read in seconds. Default is None meaning
+        that data will be read until end of stream is reached or, when reading
+        from microphone a Ctrl-C is sent.
+
+    When `input` is None, of type bytes or a raw audio files some of the
+    follwing kwargs are mandatory.
+
+    Other Parameters
+    ----------------
+    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, "any", "mix", "avg", "average"} 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* the channels of `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" (alias "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 its 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.
+    """
+
+    def __init__(
+        self,
+        input,
+        block_dur=0.01,
+        hop_dur=None,
+        record=False,
+        max_read=None,
+        **kwargs
+    ):
+        if not isinstance(input, AudioSource):
+            input = get_audio_source(input, **kwargs)
+        self._record = record
+        if record:
+            input = _Recorder(input)
+        if max_read is not None:
+            input = _Limiter(input, max_read)
+            self._max_read = max_read
+        if hop_dur is not None:
+            input = _OverlapAudioReader(input, block_dur, hop_dur)
+        else:
+            input = _FixedSizeAudioReader(input, block_dur)
+        self._audio_source = input
+
+    def __repr__(self):
+        block_dur, hop_dur, max_read = None, None, None
+        if self.block_dur is not None:
+            block_dur = "{:.3f}".format(self.block_dur)
+        if self.hop_dur is not None:
+            hop_dur = "{:.3f}".format(self.hop_dur)
+        if self.max_read is not None:
+            max_read = "{:.3f}".format(self.max_read)
+        return (
+            "{cls}(block_dur={block_dur}, "
+            "hop_dur={hop_dur}, record={rewindable}, "
+            "max_read={max_read})"
+        ).format(
+            cls=self.__class__.__name__,
+            block_dur=block_dur,
+            hop_dur=hop_dur,
+            rewindable=self._record,
+            max_read=max_read,
+        )
+
+    @property
+    def rewindable(self):
+        return self._record
+
+    @property
+    def block_dur(self):
+        return self._audio_source.block_size / self._audio_source.sr
+
+    @property
+    def hop_dur(self):
+        if hasattr(self._audio_source, "hop_dur"):
+            return self._audio_source.hop_size / self._audio_source.sr
+        return self.block_dur
+
+    @property
+    def hop_size(self):
+        if hasattr(self._audio_source, "hop_size"):
+            return self._audio_source.hop_size
+        return self.block_size
+
+    @property
+    def max_read(self):
+        try:
+            return self._audio_source.max_read
+        except AttributeError:
+            return None
+
+    def read(self):
+        return self._audio_source.read()
+
+    def __getattr__(self, name):
+        if name in ("data", "rewind") and not self.rewindable:
+            raise AttributeError(
+                "'AudioReader' has no attribute '{}'".format(name)
+            )
+        try:
+            return getattr(self._audio_source, name)
+        except AttributeError:
+            raise AttributeError(
+                "'AudioReader' has no attribute '{}'".format(name)
+            )
+
+
+# Keep AudioDataSource for compatibility
+# Remove in a future version when ADSFactory is removed
+AudioDataSource = AudioReader
+
+
+class Recorder(AudioReader):
+    """Class to read fixed-size chunks of audio data from a source and keeps
+    data in a cache. Using this class is equivalent to initializing
+    :class:`AudioReader` with `record=True`. For more information about the
+    other parameters see :class:`AudioReader`.
+
+    Once the desired amount of data is read, you can call the :func:`rewind`
+    method then get the recorded data via the :attr:`data` attribute. You can also
+    re-read cached data one window a time by calling :func:`read`.
     """
-    
-    
-    if _WITH_NUMPY:
-        
-        _formats = {1: numpy.int8 , 2: numpy.int16, 4: numpy.int32}
-
-        @staticmethod
-        def _convert(signal, sample_width):
-            return numpy.array(numpy.frombuffer(signal, dtype=AudioEnergyValidator._formats[sample_width]), dtype=numpy.float64)                             
-            
-        @staticmethod
-        def _signal_energy(signal):
-            return float(numpy.dot(signal, signal)) / len(signal)
-        
-        @staticmethod    
-        def _signal_log_energy(signal):
-            energy = AudioEnergyValidator._signal_energy(signal)
-            if energy <= 0:
-                return -200
-            return 10. * numpy.log10(energy)
-        
-    else:
-        
-        
-        _formats = {1: 'b' , 2: 'h', 4: 'i'}
-        
-        @staticmethod
-        def _convert(signal, sample_width):
-            return array("d", array(AudioEnergyValidator._formats[sample_width], signal))
-        
-        @staticmethod
-        def _signal_energy(signal):
-            energy = 0.
-            for a in signal:
-                energy += a * a
-            return energy / len(signal)
-        
-        @staticmethod    
-        def _signal_log_energy(signal):
-            energy = AudioEnergyValidator._signal_energy(signal)
-            if energy <= 0:
-                return -200
-            return 10. * math.log10(energy)
-            
-    
-    def __init__(self, sample_width, energy_threshold=45):
-        self.sample_width = sample_width
-        self._energy_threshold = energy_threshold
-        
-            
-    def is_valid(self, data):
-        """
-        Check if data is valid. Audio data will be converted into an array (of
-        signed values) of which the log energy is computed. Log energy is computed
-        as follows:
-        
-        .. code:: python
-        
-            arr = AudioEnergyValidator._convert(signal, sample_width)
-            energy = float(numpy.dot(arr, arr)) / len(arr)
-            log_energy = 10. * numpy.log10(energy)
-        
-        
-        :Parameters:
-        
-        `data` : either a *string* or a *Bytes* buffer
-            `data` is converted into a numerical array using the `sample_width`
-            given in the constructor.
-        
-        :Retruns:
-        
-        True if `log_energy` >= `energy_threshold`, False otherwise.
-        """
-        
-        signal = AudioEnergyValidator._convert(data, self.sample_width)
-        return AudioEnergyValidator._signal_log_energy(signal) >= self._energy_threshold
-    
-    def get_energy_threshold(self):
-        return self._energy_threshold
-    
-    def set_energy_threshold(self, threshold):
-        self._energy_threshold = threshold
 
+    def __init__(
+        self, input, block_dur=0.01, hop_dur=None, max_read=None, **kwargs
+    ):
+        super().__init__(
+            input,
+            block_dur=block_dur,
+            hop_dur=hop_dur,
+            record=True,
+            max_read=max_read,
+            **kwargs
+        )
diff --git a/libs/auditok/workers.py b/libs/auditok/workers.py
new file mode 100755
index 000000000..bb6d54a98
--- /dev/null
+++ b/libs/auditok/workers.py
@@ -0,0 +1,427 @@
+import os
+import sys
+from tempfile import NamedTemporaryFile
+from abc import ABCMeta, abstractmethod
+from threading import Thread
+from datetime import datetime, timedelta
+from collections import namedtuple
+import wave
+import subprocess
+from queue import Queue, Empty
+from .io import _guess_audio_format
+from .util import AudioDataSource, make_duration_formatter
+from .core import split
+from .exceptions import (
+    EndOfProcessing,
+    AudioEncodingError,
+    AudioEncodingWarning,
+)
+
+
+_STOP_PROCESSING = "STOP_PROCESSING"
+_Detection = namedtuple("_Detection", "id start end duration")
+
+
+def _run_subprocess(command):
+    try:
+        with subprocess.Popen(
+            command,
+            stdin=open(os.devnull, "rb"),
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+        ) as proc:
+            stdout, stderr = proc.communicate()
+            return proc.returncode, stdout, stderr
+    except Exception:
+        err_msg = "Couldn't export audio using command: '{}'".format(command)
+        raise AudioEncodingError(err_msg)
+
+
+class Worker(Thread, metaclass=ABCMeta):
+    def __init__(self, timeout=0.5, logger=None):
+        self._timeout = timeout
+        self._logger = logger
+        self._inbox = Queue()
+        Thread.__init__(self)
+
+    def run(self):
+        while True:
+            message = self._get_message()
+            if message == _STOP_PROCESSING:
+                break
+            if message is not None:
+                self._process_message(message)
+        self._post_process()
+
+    @abstractmethod
+    def _process_message(self, message):
+        """Process incoming messages"""
+
+    def _post_process(self):
+        pass
+
+    def _log(self, message):
+        self._logger.info(message)
+
+    def _stop_requested(self):
+        try:
+            message = self._inbox.get_nowait()
+            if message == _STOP_PROCESSING:
+                return True
+        except Empty:
+            return False
+
+    def stop(self):
+        self.send(_STOP_PROCESSING)
+        self.join()
+
+    def send(self, message):
+        self._inbox.put(message)
+
+    def _get_message(self):
+        try:
+            message = self._inbox.get(timeout=self._timeout)
+            return message
+        except Empty:
+            return None
+
+
+class TokenizerWorker(Worker, AudioDataSource):
+    def __init__(self, reader, observers=None, logger=None, **kwargs):
+        self._observers = observers if observers is not None else []
+        self._reader = reader
+        self._audio_region_gen = split(self, **kwargs)
+        self._detections = []
+        self._log_format = "[DET]: Detection {0.id} (start: {0.start:.3f}, "
+        self._log_format += "end: {0.end:.3f}, duration: {0.duration:.3f})"
+        Worker.__init__(self, timeout=0.2, logger=logger)
+
+    def _process_message(self):
+        pass
+
+    @property
+    def detections(self):
+        return self._detections
+
+    def _notify_observers(self, message):
+        for observer in self._observers:
+            observer.send(message)
+
+    def run(self):
+        self._reader.open()
+        start_processing_timestamp = datetime.now()
+        for _id, audio_region in enumerate(self._audio_region_gen, start=1):
+            timestamp = start_processing_timestamp + timedelta(
+                seconds=audio_region.meta.start
+            )
+            audio_region.meta.timestamp = timestamp
+            detection = _Detection(
+                _id,
+                audio_region.meta.start,
+                audio_region.meta.end,
+                audio_region.duration,
+            )
+            self._detections.append(detection)
+            if self._logger is not None:
+                message = self._log_format.format(detection)
+                self._log(message)
+            self._notify_observers((_id, audio_region))
+        self._notify_observers(_STOP_PROCESSING)
+        self._reader.close()
+
+    def start_all(self):
+        for observer in self._observers:
+            observer.start()
+        self.start()
+
+    def stop_all(self):
+        self.stop()
+        for observer in self._observers:
+            observer.stop()
+        self._reader.close()
+
+    def read(self):
+        if self._stop_requested():
+            return None
+        else:
+            return self._reader.read()
+
+    def __getattr__(self, name):
+        return getattr(self._reader, name)
+
+
+class StreamSaverWorker(Worker):
+    def __init__(
+        self,
+        audio_reader,
+        filename,
+        export_format=None,
+        cache_size_sec=0.5,
+        timeout=0.2,
+    ):
+        self._reader = audio_reader
+        sample_size_bytes = self._reader.sw * self._reader.ch
+        self._cache_size = cache_size_sec * self._reader.sr * sample_size_bytes
+        self._output_filename = filename
+        self._export_format = _guess_audio_format(export_format, filename)
+        if self._export_format is None:
+            self._export_format = "wav"
+        self._init_output_stream()
+        self._exported = False
+        self._cache = []
+        self._total_cached = 0
+        Worker.__init__(self, timeout=timeout)
+
+    def _get_non_existent_filename(self):
+        filename = self._output_filename + ".wav"
+        i = 0
+        while os.path.exists(filename):
+            i += 1
+            filename = self._output_filename + "({}).wav".format(i)
+        return filename
+
+    def _init_output_stream(self):
+        if self._export_format != "wav":
+            self._tmp_output_filename = self._get_non_existent_filename()
+        else:
+            self._tmp_output_filename = self._output_filename
+        self._wfp = wave.open(self._tmp_output_filename, "wb")
+        self._wfp.setframerate(self._reader.sr)
+        self._wfp.setsampwidth(self._reader.sw)
+        self._wfp.setnchannels(self._reader.ch)
+
+    @property
+    def sr(self):
+        return self._reader.sampling_rate
+
+    @property
+    def sw(self):
+        return self._reader.sample_width
+
+    @property
+    def ch(self):
+        return self._reader.channels
+
+    def __del__(self):
+        self._post_process()
+
+        if (
+            (self._tmp_output_filename != self._output_filename)
+            and self._exported
+            and os.path.exists(self._tmp_output_filename)
+        ):
+            os.remove(self._tmp_output_filename)
+
+    def _process_message(self, data):
+        self._cache.append(data)
+        self._total_cached += len(data)
+        if self._total_cached >= self._cache_size:
+            self._write_cached_data()
+
+    def _post_process(self):
+        while True:
+            try:
+                data = self._inbox.get_nowait()
+                if data != _STOP_PROCESSING:
+                    self._cache.append(data)
+                    self._total_cached += len(data)
+            except Empty:
+                break
+        self._write_cached_data()
+        self._wfp.close()
+
+    def _write_cached_data(self):
+        if self._cache:
+            data = b"".join(self._cache)
+            self._wfp.writeframes(data)
+            self._cache = []
+            self._total_cached = 0
+
+    def open(self):
+        self._reader.open()
+
+    def close(self):
+        self._reader.close()
+        self.stop()
+
+    def rewind(self):
+        # ensure compatibility with AudioDataSource with record=True
+        pass
+
+    @property
+    def data(self):
+        with wave.open(self._tmp_output_filename, "rb") as wfp:
+            return wfp.readframes(-1)
+
+    def save_stream(self):
+        if self._exported:
+            return self._output_filename
+
+        if self._export_format in ("raw", "wav"):
+            if self._export_format == "raw":
+                self._export_raw()
+            self._exported = True
+            return self._output_filename
+        try:
+            self._export_with_ffmpeg_or_avconv()
+        except AudioEncodingError:
+            try:
+                self._export_with_sox()
+            except AudioEncodingError:
+                warn_msg = "Couldn't save audio data in the desired format "
+                warn_msg += "'{}'. Either none of 'ffmpeg', 'avconv' or 'sox' "
+                warn_msg += "is installed or this format is not recognized.\n"
+                warn_msg += "Audio file was saved as '{}'"
+                raise AudioEncodingWarning(
+                    warn_msg.format(
+                        self._export_format, self._tmp_output_filename
+                    )
+                )
+        finally:
+            self._exported = True
+        return self._output_filename
+
+    def _export_raw(self):
+        with open(self._output_filename, "wb") as wfp:
+            wfp.write(self.data)
+
+    def _export_with_ffmpeg_or_avconv(self):
+        command = [
+            "-y",
+            "-f",
+            "wav",
+            "-i",
+            self._tmp_output_filename,
+            "-f",
+            self._export_format,
+            self._output_filename,
+        ]
+        returncode, stdout, stderr = _run_subprocess(["ffmpeg"] + command)
+        if returncode != 0:
+            returncode, stdout, stderr = _run_subprocess(["avconv"] + command)
+            if returncode != 0:
+                raise AudioEncodingError(stderr)
+        return stdout, stderr
+
+    def _export_with_sox(self):
+        command = [
+            "sox",
+            "-t",
+            "wav",
+            self._tmp_output_filename,
+            self._output_filename,
+        ]
+        returncode, stdout, stderr = _run_subprocess(command)
+        if returncode != 0:
+            raise AudioEncodingError(stderr)
+        return stdout, stderr
+
+    def close_output(self):
+        self._wfp.close()
+
+    def read(self):
+        data = self._reader.read()
+        if data is not None:
+            self.send(data)
+        else:
+            self.send(_STOP_PROCESSING)
+        return data
+
+    def __getattr__(self, name):
+        if name == "data":
+            return self.data
+        return getattr(self._reader, name)
+
+
+class PlayerWorker(Worker):
+    def __init__(self, player, progress_bar=False, timeout=0.2, logger=None):
+        self._player = player
+        self._progress_bar = progress_bar
+        self._log_format = "[PLAY]: Detection {id} played"
+        Worker.__init__(self, timeout=timeout, logger=logger)
+
+    def _process_message(self, message):
+        _id, audio_region = message
+        if self._logger is not None:
+            message = self._log_format.format(id=_id)
+            self._log(message)
+        audio_region.play(
+            player=self._player, progress_bar=self._progress_bar, leave=False
+        )
+
+
+class RegionSaverWorker(Worker):
+    def __init__(
+        self,
+        filename_format,
+        audio_format=None,
+        timeout=0.2,
+        logger=None,
+        **audio_parameters
+    ):
+        self._filename_format = filename_format
+        self._audio_format = audio_format
+        self._audio_parameters = audio_parameters
+        self._debug_format = "[SAVE]: Detection {id} saved as '{filename}'"
+        Worker.__init__(self, timeout=timeout, logger=logger)
+
+    def _process_message(self, message):
+        _id, audio_region = message
+        filename = self._filename_format.format(
+            id=_id,
+            start=audio_region.meta.start,
+            end=audio_region.meta.end,
+            duration=audio_region.duration,
+        )
+        filename = audio_region.save(
+            filename, self._audio_format, **self._audio_parameters
+        )
+        if self._logger:
+            message = self._debug_format.format(id=_id, filename=filename)
+            self._log(message)
+
+
+class CommandLineWorker(Worker):
+    def __init__(self, command, timeout=0.2, logger=None):
+        self._command = command
+        Worker.__init__(self, timeout=timeout, logger=logger)
+        self._debug_format = "[COMMAND]: Detection {id} command: '{command}'"
+
+    def _process_message(self, message):
+        _id, audio_region = message
+        with NamedTemporaryFile(delete=False) as file:
+            filename = audio_region.save(file.name, audio_format="wav")
+            command = self._command.format(file=filename)
+            os.system(command)
+            if self._logger is not None:
+                message = self._debug_format.format(id=_id, command=command)
+                self._log(message)
+
+
+class PrintWorker(Worker):
+    def __init__(
+        self,
+        print_format="{start} {end}",
+        time_format="%S",
+        timestamp_format="%Y/%m/%d %H:%M:%S.%f",
+        timeout=0.2,
+    ):
+
+        self._print_format = print_format
+        self._format_time = make_duration_formatter(time_format)
+        self._timestamp_format = timestamp_format
+        self.detections = []
+        Worker.__init__(self, timeout=timeout)
+
+    def _process_message(self, message):
+        _id, audio_region = message
+        timestamp = audio_region.meta.timestamp
+        timestamp = timestamp.strftime(self._timestamp_format)
+        text = self._print_format.format(
+            id=_id,
+            start=self._format_time(audio_region.meta.start),
+            end=self._format_time(audio_region.meta.end),
+            duration=self._format_time(audio_region.duration),
+            timestamp=timestamp,
+        )
+        print(text)