Metadata-Version: 2.1
Name: auditok
Version: 0.2.0
Summary: A module for Audio/Acoustic Activity Detection
Home-page: http://github.com/amsehili/auditok/
Author: Amine Sehili
Author-email: amine.sehili@gmail.com
License: MIT
Description: auditok, an AUDIo TOKenization tool
        ===================================
        
        .. image:: https://github.com/amsehili/auditok/raw/master/doc/figures/auditok-logo.png
            :align: center
        
        .. image:: https://travis-ci.org/amsehili/auditok.svg?branch=master
            :target: https://travis-ci.org/amsehili/auditok
            :alt: Build status
        
        .. image:: https://readthedocs.org/projects/auditok/badge/?version=v0.2.0
            :target: https://auditok.readthedocs.io/en/v0.2.0/
            :alt: Documentation status
        
        ``auditok`` is an **Audio Activity Detection** tool that can process online data
        (read from an audio device or from standard input) as well as audio files.
        It can be used as a command-line program or by calling its API.
        
        The documentation for this version can be found on
        `readthedocs. <https://auditok.readthedocs.io/en/v0.2.0/>`_
        
        
        Installation
        ------------
        
        A basic version of ``auditok`` will run with standard Python (>=3.4). However,
        without installing additional dependencies, ``auditok`` can only deal with audio
        files in *wav* or *raw* formats. if you want more features, the following
        packages are needed:
        
        - `pydub <https://github.com/jiaaro/pydub>`_ : read audio files in popular audio formats (ogg, mp3, etc.) or extract audio from a video file.
        - `pyaudio <https://people.csail.mit.edu/hubert/pyaudio>`_ : read audio data from the microphone and play audio back.
        - `tqdm <https://github.com/tqdm/tqdm>`_ : show progress bar while playing audio clips.
        - `matplotlib <https://matplotlib.org/stable/index.html>`_ : plot audio signal and detections.
        - `numpy <https://numpy.org/>`_ : required by matplotlib. Also used for some math operations instead of standard python if available.
        
        Install the latest stable version with pip:
        
        
        .. code:: bash
        
            sudo pip install auditok
        
        
        Install the latest development version from github:
        
        .. code:: bash
        
            pip install git+https://github.com/amsehili/auditok
        
        or
        
        .. code:: bash
        
            git clone https://github.com/amsehili/auditok.git
            cd auditok
            python setup.py install
        
        
        Basic example
        -------------
        
        .. code:: python
        
            import auditok
        
            # split returns a generator of AudioRegion objects
            audio_regions = auditok.split(
                "audio.wav",
                min_dur=0.2,     # minimum duration of a valid audio event in seconds
                max_dur=4,       # maximum duration of an event
                max_silence=0.3, # maximum duration of tolerated continuous silence within an event
                energy_threshold=55 # threshold of detection
            )
        
            for i, r in enumerate(audio_regions):
        
                # Regions returned by `split` have 'start' and 'end' metadata fields
                print("Region {i}: {r.meta.start:.3f}s -- {r.meta.end:.3f}s".format(i=i, r=r))
        
                # play detection
                # r.play(progress_bar=True)
        
                # region's metadata can also be used with the `save` method
                # (no need to explicitly specify region's object and `format` arguments)
                filename = r.save("region_{meta.start:.3f}-{meta.end:.3f}.wav")
                print("region saved as: {}".format(filename))
        
        output example:
        
        .. code:: bash
        
            Region 0: 0.700s -- 1.400s
            region saved as: region_0.700-1.400.wav
            Region 1: 3.800s -- 4.500s
            region saved as: region_3.800-4.500.wav
            Region 2: 8.750s -- 9.950s
            region saved as: region_8.750-9.950.wav
            Region 3: 11.700s -- 12.400s
            region saved as: region_11.700-12.400.wav
            Region 4: 15.050s -- 15.850s
            region saved as: region_15.050-15.850.wav
        
        
        Split and plot
        --------------
        
        Visualize audio signal and detections:
        
        .. code:: python
        
            import auditok
            region = auditok.load("audio.wav") # returns an AudioRegion object
            regions = region.split_and_plot(...) # or just region.splitp()
        
        output figure:
        
        .. image:: https://raw.githubusercontent.com/amsehili/auditok/master/doc/figures/example_1.png
        
        
        Limitations
        -----------
        
        Currently, the core detection algorithm is based on the energy of audio signal.
        While this is fast and works very well for audio streams with low background
        noise (e.g., podcasts with few people talking, language lessons, audio recorded
        in a rather quiet environment, etc.) the performance can drop as the level of
        noise increases. Furthermore, the algorithm makes now distinction between speech
        and other kinds of sounds, so you shouldn't use it for Voice Activity Detection
        if your audio data also contain non-speech events.
        
        License
        -------
        MIT.
        
Platform: ANY
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: Telecommunications Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Topic :: Multimedia :: Sound/Audio :: Analysis
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Provides: auditok
Description-Content-Type: text/x-rst
