AudiooPy 0.4

Audio manager in Python Object-Oriented Programming

-------------------------------------------------------------------------

   █████╗  ██╗   ██╗ ██████╗  ██╗  ██████╗   ██████╗  ██████╗  ██╗   ██╗
  ██╔══██╗ ██║   ██║ ██╔══██╗ ██║ ██╔═══██╗ ██╔═══██╗ ██╔══██╗ ╚██╗ ██╔╝ 
  ███████║ ██║   ██║ ██║  ██║ ██║ ██║   ██║ ██║   ██║ ██████╔╝  ╚████╔╝ 
  ██╔══██║ ██║   ██║ ██║  ██║ ██║ ██║   ██║ ██║   ██║ ██╔═══╝    ╚██╔╝  
  ██║  ██║ ╚██████╔╝ ██████╔╝ ██║ ╚██████╔╝ ╚██████╔╝ ██║         ██║   
  ╚═╝  ╚═╝  ╚═════╝  ╚═════╝  ╚═╝  ╚═════╝   ╚═════╝  ╚═╝         ╚═╝  

       an Audio manager in Python Object-Oriented Programming

Copyright (C) 2024 Laboratoire Parole et Langage, Aix-en-Provence, France
-------------------------------------------------------------------------

AudiooPy description

Overview

Uses cases

Either, you have an audio file, and you want to apply some operations the Python audioop library is doing before its removal of the distribution. Or, you have a speech audio file, and you want to detect automatically speech segments, also called IPUs - Inter-Pausal Units.

And... You don't want to install a bunch of other libraries! Then AudiooPy is the library you need.

Features

AudiooPy contains some useful operations on sound files and sound fragments. It operates on sound frames, meaning they consist of signed integer samples 8, 16, or 32 bits wide, stored in bytes-like objects.

Among others, it allows the followings:

• Audio reader/writer for wav -- based on Python standard library
• Manipulate raw audio data
• Audio mixer
• Channels extractor
• Channels mixer
• Automated calculation of statistical descriptors for audio data
• High-fidelity automatic detection of sounding segments in speech - also called "Search for IPUs". See: https://hal.archives-ouvertes.fr/hal-03697808

Main advantages

AudiooPy is self-implemented, it does not require any other external library.

• easily customizable: it's a pure python library in Object-Oriented Programming
• open-source: easily add new features and functionalities
• scalable: no limit to support numerous audio files
• portable: can be used on any system - as soon as python is available
• reliable: code is tested at 77%, and the search for IPUs is scientifically validated

Install AudiooPy

From pypi.org:

> python -m pip install AudiooPy

From its wheel package:

Download the wheel file (AudiooPy-xxx.whl) and install it in your python environment with:

> python -m pip install <AudiooPy-xxx.whl>

From its repo:

Download the repository and unpack it, or clone with git. Optionally, it can be installed with:

> python -m pip install .

Install all the optional dependencies with:

> python -m pip install ".[docs, tests]"

AudiooPy content

AudiooPy tool includes the following folders and files:

1. "audioopy": the source code package
2. "docs": the documentation of audioopy library in both HTML and Markdown
3. "tests": the tests of the source code
4. "scripts": a few python scripts using audioopy to manipulate audio files

Quick Start

A few scripts are already available in the scripts folder. Try for example:

> python ./scripts/audioinfo.py -w samples/oriana1.wav

Operates on audio

Or, you can implement it yourself! Open an audio file and get some information with:

>>> import audioopy.aio
>>> audio = audioopy.aio.open("tests/samples/oriana1.wav")
>>> audio.get_sampwidth()
>>> audio.get_framerate()
>>> audio.get_duration()
>>> audio.get_nchannels()
>>> audio.get_nframes()
>>> audio.rms()
>>> audio.clipping_rate(0.4)
>>> # Extract the channel
>>> audio.extract_channel(0)

Search for IPUs

Below is an example of the automatic detection of sounding segments, like described in the following reference:

Brigitte Bigi, Béatrice Priego-Valverde (2022). The automatic search for sounding segments of SPPAS: application to Cheese! corpus. Human Language Technology. Challenges for Computer Science and Linguistics, LNAI, LNCS 13212, pp. 16-27. https://hal.archives-ouvertes.fr/hal-03697808

Let's go:

>>> from audioopy.ipus import SearchForIPUs
>>>  # Create the instance and fix options
>>> searcher = SearchForIPUs(channel=audio[0])
>>>  # Fix options
>>> searcher.set_vol_threshold(0)  # auto
>>> searcher.set_win_length(0.02)
>>> searcher.set_min_sil(0.25)
>>> searcher.set_min_ipu(0.2)
>>> searcher.set_shift_start(0.02)
>>> searcher.set_shift_end(0.02)
>>>  # Process the data and get the list of IPUs
>>> tracks = searcher.get_tracks(time_domain=True)

Launch 'python scripts/sample.py' to see the results.

Make the doc

The API documentation is available in the docs folder. Click the file index.html to browse throw the documented classes.

To re-generate the doc, install the required external programs, then launch the doc generator:

>python -m pip install ".[docs]"
>python makedoc.py

Projects using AudiooPy

AudiooPy was initially developed within SPPAS https://sppas.org. It was extracted from its original software in 2024 by the author to lead its own life as standalone package.

Help / How to contribute

If you plan to contribute to the code or to report a bug, please send an e-mail to the author. Any and all constructive comments are welcome.

License/Copyright

See the accompanying LICENSE and AUTHORS.md files for the full list of contributors.

Copyright (C) 2024 Brigitte Bigi - Laboratoire Parole et Langage, Aix-en-Provence, France

This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License along with this program. If not, see https://www.gnu.org/licenses/.

Changes

• Version 0.1:

  • Initial version, extracted from SPPAS 4.17.
  • A few self-implemented functions into AudioFrames() instead of using 'audioop' standard library.

• Version 0.2:

  • Self-implemented functions into AudioFrames(), except for resample() which is only partially self-implemented.
  • Added function clip() in AudioFrames().
  • Added the error number 2090: NumberFramesError.
  • Updated scripts.

• Version 0.3:

  • self-implemented resample() is continued: it works with output=16kHz, input=(32kHz, 48kHz).

• Version 0.4:

  • included the full implementation of the Search for IPUs algorithm - migrated from SPPAS.
  • changed license to AGPL.