audio-helper 1.5.5__tar.gz

audio_helper-1.5.5/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Warith HARCHAOUI
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

audio_helper-1.5.5/PKG-INFO

@@ -0,0 +1,228 @@
+Metadata-Version: 2.4
+Name: audio-helper
+Version: 1.5.5
+Summary: Audio Helper — utility functions for processing audio files exposed as library, argparse CLI, click CLI, FastAPI HTTP surface and MCP tools. Load audio, convert formats, separate audio sources (Demucs), split and concatenate audio. Shannon-correct resampling via ffmpeg/libswresample.
+Author-email: Warith HARCHAOUI <warithmetics@deraison.ai>
+License: BSD-3-Clause
+Project-URL: Homepage, https://github.com/warith-harchaoui/audio-helper
+Project-URL: Issues, https://github.com/warith-harchaoui/audio-helper/issues
+Keywords: audio,ffmpeg,scipy,demucs,resampling,pcm
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Sound/Audio
+Classifier: Topic :: Multimedia :: Sound/Audio :: Conversion
+Requires-Python: <3.14,>=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: os-helper>=1.4.2
+Requires-Dist: ffmpeg-python<0.3,>=0.2.0
+Requires-Dist: tqdm<5,>=4.67.1
+Requires-Dist: scipy<2,>=1.15.1
+Requires-Dist: numpy>=1.24
+Provides-Extra: demucs
+Requires-Dist: torch<3,>=2.5.1; extra == "demucs"
+Requires-Dist: torchaudio<3,>=2.5.1; extra == "demucs"
+Provides-Extra: cli
+Requires-Dist: click<9,>=8.1; extra == "cli"
+Provides-Extra: api
+Requires-Dist: fastapi<1,>=0.111; extra == "api"
+Requires-Dist: uvicorn<1,>=0.30; extra == "api"
+Requires-Dist: python-multipart<1,>=0.0.9; extra == "api"
+Provides-Extra: mcp
+Requires-Dist: fastapi-mcp<1,>=0.3; extra == "mcp"
+Requires-Dist: fastapi<1,>=0.111; extra == "mcp"
+Requires-Dist: uvicorn<1,>=0.30; extra == "mcp"
+Requires-Dist: python-multipart<1,>=0.0.9; extra == "mcp"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: httpx>=0.27; extra == "dev"
+Requires-Dist: click<9,>=8.1; extra == "dev"
+Requires-Dist: fastapi<1,>=0.111; extra == "dev"
+Requires-Dist: python-multipart<1,>=0.0.9; extra == "dev"
+Requires-Dist: fastapi-mcp<1,>=0.3; extra == "dev"
+Dynamic: license-file
+
+# Audio Helper
+
+[🇫🇷](https://github.com/warith-harchaoui/audio-helper/blob/main/LISEZMOI.md) · [🇬🇧](https://github.com/warith-harchaoui/audio-helper/blob/main/README.md)
+
+[![CI](https://github.com/warith-harchaoui/audio-helper/actions/workflows/ci.yml/badge.svg)](https://github.com/warith-harchaoui/audio-helper/actions/workflows/ci.yml) [![License: BSD-3-Clause](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](LICENSE) [![Python](https://img.shields.io/badge/python-3.10%E2%80%933.13-blue.svg)](#)
+
+`Audio Helper` belongs to a collection of libraries called `AI Helpers` developed for building Artificial Intelligence.
+
+[🌍 AI Helpers](https://harchaoui.org/warith/ai-helpers)
+
+[![logo](https://raw.githubusercontent.com/warith-harchaoui/audio-helper/main/assets/logo.png)](https://harchaoui.org/warith/ai-helpers)
+
+Audio Helper is a Python library that provides utility functions for processing audio files. It includes features like loading audio, converting formats, separating audio sources, and splitting and concatenating audio files.
+
+# Installation
+
+**Prerequisites** — **Python 3.10–3.13** and **git**, **ffmpeg**, cross-platform:
+
+- 🍎 **macOS** ([Homebrew](https://brew.sh)): `brew install python git ffmpeg`
+- 🐧 **Ubuntu/Debian**: `sudo apt update && sudo apt install -y python3 python3-pip git ffmpeg`
+- 🪟 **Windows** (PowerShell): `winget install Python.Python.3.12 Git.Git Gyan.FFmpeg`
+
+Then install the package:
+
+
+## Install Package
+
+We recommend using Python environments. Check this link if you're unfamiliar with setting one up:
+
+[🥸 Tech tips](https://harchaoui.org/warith/4ml/#install)
+
+## Install `ffmpeg` 
+To install Audio Helper, you must install `ffmpeg`:
+
+- For macos 🍎
+  
+  Get [brew](https://brew.sh)
+  ```bash
+  brew install ffmpeg
+  ```
+- For Ubuntu 🐧
+  ```bash
+  sudo apt install ffmpeg
+  ```
+- For Windows 🪟
+  
+  Go to the [FFmpeg website](https://ffmpeg.org/download.html) and follow the instructions for downloading FFmpeg. You'll need to manually add FFmpeg to your system PATH.
+  
+and finally we still discuss between different python package managers and try to support as much as possible
+
+Audio Helper ships in two flavors. Pick the one you need:
+
+```bash
+# Core audio utilities only (load, convert, split, concatenate, silent audio, chunks)
+pip install --force-reinstall --no-cache-dir \
+  "git+https://github.com/warith-harchaoui/audio-helper.git@v1.5.5"
+
+# Add Demucs source separation (pulls in torch + torchaudio, ~2 GB)
+pip install --force-reinstall --no-cache-dir \
+  "audio-helper[demucs] @ git+https://github.com/warith-harchaoui/audio-helper.git@v1.5.5"
+```
+
+If you call `separate_sources` without the `[demucs]` extra, the function raises an `ImportError` pointing you back here.
+
+# Usage
+
+For the full catalog of recipes, see [📋 EXAMPLES.md](https://github.com/warith-harchaoui/audio-helper/blob/main/EXAMPLES.md).
+
+Here’s an example of how to use Audio Helper to load, convert, and split an audio file:
+
+(download [example.mp3](https://harchaoui.org/warith/example.mp3) )
+
+It is part of a JFK speech that is badly recorded
+
+```python
+import audio_helper as ah
+
+# Load an audio file
+audio_file = "example.mp3"
+audio, sample_rate = ah.load_audio(audio_file)
+
+# Convert the audio file to a different format
+output_audio = "audio_tests/example.wav"
+ah.sound_converter(audio_file, output_audio)
+
+# Split the audio file into chunks of 30 seconds
+chunks = ah.split_audio_regularly(audio_file, "audio_tests/chunks_folder", split_time=30.0, overwrite = True)
+# Concatenate the chunks back together
+new_concatenated_audio = "audio_tests/concatenated.wav"
+concatenated_audio = ah.audio_concatenation(chunks, output_audio_filename = new_concatenated_audio)
+```
+
+Another cool example is about source separation (DEMUCS from META) with AI separating one audio track into 4 tracks:
+- vocals
+- drums
+- bass
+- other
+
+It works with speech and songs
+
+```python
+import audio_helper as ah
+
+audio_path = "input_audio.m4a"
+
+sources = ah.separate_sources(
+    audio_path,
+    output_folder="audio_tests",
+    device = "cpu", # or "cuda" if GPU or nothing to let it decide
+    nb_workers = 4, # ignored if not cpu
+    output_format = "mp3",
+)
+
+print(sources)
+# {'vocals': 'audio_tests/vocals.mp3', 'drums': 'audio_tests/drums.mp3', 'bass': 'audio_tests/bass.mp3', 'other': 'audio_tests/other.mp3'}
+```
+
+# Features
+- Audio Loading: load files with optional resampling and mono downmix.
+- Sound Conversion: ffmpeg-backed format/sample-rate/channels conversion.
+- Source Separation: vocals / drums / bass / other via Demucs (optional `[demucs]` extra).
+- Audio Splitting: fixed-duration chunks and arbitrary `[start, end]` slices.
+- Concatenation: head-to-tail join into any ffmpeg-supported container.
+- Silent Audio Generation: write silence of a specified duration.
+- Room-Tone Mixing: pink/white/brown ambient noise to mask edits between cuts.
+- Similarity: MFCC-based `sound_resemblance` score for A/B comparison.
+- Feature Extraction: scipy-based Mel / MFCC primitives.
+
+# Multi-surface exposure
+
+`audio-helper` is not just a library — the same functions are exposed
+as a CLI, a FastAPI HTTP surface, and an MCP tool set:
+
+```bash
+# Python library (default)
+import audio_helper as ah
+
+# argparse-based CLI (installed automatically)
+audio-helper convert --input in.mp3 --output out.wav --freq 44100
+audio-helper split --input in.mp3 --output-dir chunks/ --seconds 30
+audio-helper separate --input mix.mp3 --output-dir stems/
+audio-helper resemblance --a a.mp3 --b b.mp3
+
+# click-based CLI twin (needs the [cli] extra)
+pip install 'audio-helper[cli] @ git+https://github.com/warith-harchaoui/audio-helper.git@v1.5.5'
+audio-helper-click convert --input in.mp3 --output out.wav --freq 44100
+
+# FastAPI HTTP surface (needs the [api] extra)
+pip install 'audio-helper[api] @ git+https://github.com/warith-harchaoui/audio-helper.git@v1.5.5'
+uvicorn audio_helper.api:app --port 8000
+# → OpenAPI docs at http://localhost:8000/docs
+
+# MCP tools over FastAPI (needs the [api,mcp] extras)
+pip install 'audio-helper[api,mcp] @ git+https://github.com/warith-harchaoui/audio-helper.git@v1.5.5'
+audio-helper-mcp                  # serves FastAPI + MCP on port 8000
+```
+
+Docker image (light, without Demucs by default):
+
+```bash
+docker build -t audio-helper .
+docker run --rm -p 8000:8000 audio-helper
+# with Demucs:
+docker build --build-arg WITH_DEMUCS=1 -t audio-helper:demucs .
+```
+
+An innovative GUI plan (canvas-based recipe editor, ear-first
+comparator, MFCC-cluster batch view) lives in [GUI.md](https://github.com/warith-harchaoui/audio-helper/blob/main/GUI.md).
+
+The competitive landscape (librosa, torchaudio, pydub, essentia,
+Demucs, Spleeter, …) is analysed in [LANDSCAPE.md](https://github.com/warith-harchaoui/audio-helper/blob/main/LANDSCAPE.md).
+
+# Author
+ - [Warith HARCHAOUI](https://linkedin.com/in/warith-harchaoui)
+
+# Acknowledgements
+Special thanks to [Mohamed Chelali](https://mchelali.github.io) and [Bachir Zerroug](https://www.linkedin.com/in/bachirzerroug) for fruitful discussions.

audio_helper-1.5.5/README.md

@@ -0,0 +1,177 @@
+# Audio Helper
+
+[🇫🇷](https://github.com/warith-harchaoui/audio-helper/blob/main/LISEZMOI.md) · [🇬🇧](https://github.com/warith-harchaoui/audio-helper/blob/main/README.md)
+
+[![CI](https://github.com/warith-harchaoui/audio-helper/actions/workflows/ci.yml/badge.svg)](https://github.com/warith-harchaoui/audio-helper/actions/workflows/ci.yml) [![License: BSD-3-Clause](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](LICENSE) [![Python](https://img.shields.io/badge/python-3.10%E2%80%933.13-blue.svg)](#)
+
+`Audio Helper` belongs to a collection of libraries called `AI Helpers` developed for building Artificial Intelligence.
+
+[🌍 AI Helpers](https://harchaoui.org/warith/ai-helpers)
+
+[![logo](https://raw.githubusercontent.com/warith-harchaoui/audio-helper/main/assets/logo.png)](https://harchaoui.org/warith/ai-helpers)
+
+Audio Helper is a Python library that provides utility functions for processing audio files. It includes features like loading audio, converting formats, separating audio sources, and splitting and concatenating audio files.
+
+# Installation
+
+**Prerequisites** — **Python 3.10–3.13** and **git**, **ffmpeg**, cross-platform:
+
+- 🍎 **macOS** ([Homebrew](https://brew.sh)): `brew install python git ffmpeg`
+- 🐧 **Ubuntu/Debian**: `sudo apt update && sudo apt install -y python3 python3-pip git ffmpeg`
+- 🪟 **Windows** (PowerShell): `winget install Python.Python.3.12 Git.Git Gyan.FFmpeg`
+
+Then install the package:
+
+
+## Install Package
+
+We recommend using Python environments. Check this link if you're unfamiliar with setting one up:
+
+[🥸 Tech tips](https://harchaoui.org/warith/4ml/#install)
+
+## Install `ffmpeg` 
+To install Audio Helper, you must install `ffmpeg`:
+
+- For macos 🍎
+  
+  Get [brew](https://brew.sh)
+  ```bash
+  brew install ffmpeg
+  ```
+- For Ubuntu 🐧
+  ```bash
+  sudo apt install ffmpeg
+  ```
+- For Windows 🪟
+  
+  Go to the [FFmpeg website](https://ffmpeg.org/download.html) and follow the instructions for downloading FFmpeg. You'll need to manually add FFmpeg to your system PATH.
+  
+and finally we still discuss between different python package managers and try to support as much as possible
+
+Audio Helper ships in two flavors. Pick the one you need:
+
+```bash
+# Core audio utilities only (load, convert, split, concatenate, silent audio, chunks)
+pip install --force-reinstall --no-cache-dir \
+  "git+https://github.com/warith-harchaoui/audio-helper.git@v1.5.5"
+
+# Add Demucs source separation (pulls in torch + torchaudio, ~2 GB)
+pip install --force-reinstall --no-cache-dir \
+  "audio-helper[demucs] @ git+https://github.com/warith-harchaoui/audio-helper.git@v1.5.5"
+```
+
+If you call `separate_sources` without the `[demucs]` extra, the function raises an `ImportError` pointing you back here.
+
+# Usage
+
+For the full catalog of recipes, see [📋 EXAMPLES.md](https://github.com/warith-harchaoui/audio-helper/blob/main/EXAMPLES.md).
+
+Here’s an example of how to use Audio Helper to load, convert, and split an audio file:
+
+(download [example.mp3](https://harchaoui.org/warith/example.mp3) )
+
+It is part of a JFK speech that is badly recorded
+
+```python
+import audio_helper as ah
+
+# Load an audio file
+audio_file = "example.mp3"
+audio, sample_rate = ah.load_audio(audio_file)
+
+# Convert the audio file to a different format
+output_audio = "audio_tests/example.wav"
+ah.sound_converter(audio_file, output_audio)
+
+# Split the audio file into chunks of 30 seconds
+chunks = ah.split_audio_regularly(audio_file, "audio_tests/chunks_folder", split_time=30.0, overwrite = True)
+# Concatenate the chunks back together
+new_concatenated_audio = "audio_tests/concatenated.wav"
+concatenated_audio = ah.audio_concatenation(chunks, output_audio_filename = new_concatenated_audio)
+```
+
+Another cool example is about source separation (DEMUCS from META) with AI separating one audio track into 4 tracks:
+- vocals
+- drums
+- bass
+- other
+
+It works with speech and songs
+
+```python
+import audio_helper as ah
+
+audio_path = "input_audio.m4a"
+
+sources = ah.separate_sources(
+    audio_path,
+    output_folder="audio_tests",
+    device = "cpu", # or "cuda" if GPU or nothing to let it decide
+    nb_workers = 4, # ignored if not cpu
+    output_format = "mp3",
+)
+
+print(sources)
+# {'vocals': 'audio_tests/vocals.mp3', 'drums': 'audio_tests/drums.mp3', 'bass': 'audio_tests/bass.mp3', 'other': 'audio_tests/other.mp3'}
+```
+
+# Features
+- Audio Loading: load files with optional resampling and mono downmix.
+- Sound Conversion: ffmpeg-backed format/sample-rate/channels conversion.
+- Source Separation: vocals / drums / bass / other via Demucs (optional `[demucs]` extra).
+- Audio Splitting: fixed-duration chunks and arbitrary `[start, end]` slices.
+- Concatenation: head-to-tail join into any ffmpeg-supported container.
+- Silent Audio Generation: write silence of a specified duration.
+- Room-Tone Mixing: pink/white/brown ambient noise to mask edits between cuts.
+- Similarity: MFCC-based `sound_resemblance` score for A/B comparison.
+- Feature Extraction: scipy-based Mel / MFCC primitives.
+
+# Multi-surface exposure
+
+`audio-helper` is not just a library — the same functions are exposed
+as a CLI, a FastAPI HTTP surface, and an MCP tool set:
+
+```bash
+# Python library (default)
+import audio_helper as ah
+
+# argparse-based CLI (installed automatically)
+audio-helper convert --input in.mp3 --output out.wav --freq 44100
+audio-helper split --input in.mp3 --output-dir chunks/ --seconds 30
+audio-helper separate --input mix.mp3 --output-dir stems/
+audio-helper resemblance --a a.mp3 --b b.mp3
+
+# click-based CLI twin (needs the [cli] extra)
+pip install 'audio-helper[cli] @ git+https://github.com/warith-harchaoui/audio-helper.git@v1.5.5'
+audio-helper-click convert --input in.mp3 --output out.wav --freq 44100
+
+# FastAPI HTTP surface (needs the [api] extra)
+pip install 'audio-helper[api] @ git+https://github.com/warith-harchaoui/audio-helper.git@v1.5.5'
+uvicorn audio_helper.api:app --port 8000
+# → OpenAPI docs at http://localhost:8000/docs
+
+# MCP tools over FastAPI (needs the [api,mcp] extras)
+pip install 'audio-helper[api,mcp] @ git+https://github.com/warith-harchaoui/audio-helper.git@v1.5.5'
+audio-helper-mcp                  # serves FastAPI + MCP on port 8000
+```
+
+Docker image (light, without Demucs by default):
+
+```bash
+docker build -t audio-helper .
+docker run --rm -p 8000:8000 audio-helper
+# with Demucs:
+docker build --build-arg WITH_DEMUCS=1 -t audio-helper:demucs .
+```
+
+An innovative GUI plan (canvas-based recipe editor, ear-first
+comparator, MFCC-cluster batch view) lives in [GUI.md](https://github.com/warith-harchaoui/audio-helper/blob/main/GUI.md).
+
+The competitive landscape (librosa, torchaudio, pydub, essentia,
+Demucs, Spleeter, …) is analysed in [LANDSCAPE.md](https://github.com/warith-harchaoui/audio-helper/blob/main/LANDSCAPE.md).
+
+# Author
+ - [Warith HARCHAOUI](https://linkedin.com/in/warith-harchaoui)
+
+# Acknowledgements
+Special thanks to [Mohamed Chelali](https://mchelali.github.io) and [Bachir Zerroug](https://www.linkedin.com/in/bachirzerroug) for fruitful discussions.

audio_helper-1.5.5/audio_helper/__init__.py

@@ -0,0 +1,55 @@
+"""
+Audio Helper — public API surface.
+
+Re-exports the utility functions from :mod:`audio_helper.main` so that
+downstream code can simply write ``import audio_helper as ah`` and reach
+every supported operation (load, save, convert, split, concatenate,
+silence generation, room-tone mix, MFCC similarity, and optional Demucs
+source separation) without knowing about the module layout.
+
+Usage Example
+-------------
+>>> import audio_helper as ah
+>>> audio, sr = ah.load_audio("example.mp3", to_numpy=True, to_mono=True)
+>>> ah.sound_converter("example.mp3", "example.wav")
+>>> chunks = ah.split_audio_regularly("example.mp3", "chunks/", split_time=30.0)
+
+Author
+------
+Warith Harchaoui, Ph.D. — https://linkedin.com/in/warith-harchaoui/
+"""
+
+__author__ = "Warith Harchaoui, Ph.D."
+__email__ = "warithmetics@deraison.ai"
+
+# Specify the public API of this module using __all__
+__all__ = [
+    "is_valid_audio_file",
+    "get_audio_duration",
+    "load_audio",
+    "sound_converter",
+    "separate_sources",
+    "extract_audio_chunk",
+    "generate_silent_audio",
+    "audio_concatenation",
+    "mix_room_tone",
+    "split_audio_regularly",
+    "save_audio",
+    "sound_resemblance",
+]
+
+
+from .main import (
+    is_valid_audio_file,
+    get_audio_duration,
+    load_audio,
+    sound_converter,
+    separate_sources,
+    extract_audio_chunk,
+    generate_silent_audio,
+    audio_concatenation,
+    mix_room_tone,
+    split_audio_regularly,
+    save_audio,
+    sound_resemblance,
+)