modusa 0.2.22__py3-none-any.whl → 0.3__py3-none-any.whl

{modusa-0.2.22.dist-info → modusa-0.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: modusa
-Version: 0.2.22
+Version: 0.3
 Summary: A modular signal analysis python library.
 Author-Email: Ankit Anand <ankit0.anand0@gmail.com>
 License: MIT
@@ -8,23 +8,14 @@ Requires-Python: >=3.12
 Requires-Dist: numpy>=2.2.6
 Requires-Dist: matplotlib>=3.10.3
 Requires-Dist: yt-dlp>=2025.6.30
-Requires-Dist: librosa==0.10.1
+Requires-Dist: librosa==0.11.0
 Requires-Dist: IPython>=8.0.0
+Requires-Dist: pyloudnorm>=0.1.1
 Description-Content-Type: text/markdown
 
 # modusa
 
-[**modusa**](https://meluron-toolbox.github.io/modusa/) is a modular framework for audio signal analysis and processing, designed to help audio researchers and developers build DSP chains with minimal code.
-
----
-
-## Core Components
-
-- ⚙️ **modusa Signals**
-- 🧩 **modusa Plugins**
-- 📊 **modusa Genetators**
-- 📥 **modusa I/O**
-- ♻️ **modusa Engines**
+[**modusa**](https://meluron-toolbox.github.io/modusa/) is a library with utility tools especially for audio signals.
 
 ---
 
@@ -33,9 +24,7 @@ Description-Content-Type: text/markdown
 > modusa is under active development. You can install the latest version via:
 
 ```bash
-git clone https://github.com/meluron/modusa.git
-cd modusa
-pdm install
+pip install modusa
 ```
 
 ---

modusa-0.3.dist-info/RECORD

@@ -0,0 +1,60 @@
+modusa-0.3.dist-info/METADATA,sha256=4haDvOLjhY_sygHcMExMqMNXEVsUkNHfgoHpXWaX1PU,1236
+modusa-0.3.dist-info/WHEEL,sha256=9P2ygRxDrTJz3gsagc0Z96ukrxjr-LFBGOgv3AuKlCA,90
+modusa-0.3.dist-info/entry_points.txt,sha256=fmKpleVXj6CdaBVL14WoEy6xx7JQCs85jvzwTi3lePM,73
+modusa-0.3.dist-info/licenses/LICENSE.md,sha256=JTaXAjx5awk76VArKCx5dUW8vmLEWsL_ZlR7-umaHbA,1078
+modusa/.DS_Store,sha256=_gm6qJREwfMi8dE7n5S89_RG46u5t3xHyD-smNhtNoM,6148
+modusa/__init__.py,sha256=AALG_17vibpDZbo0MymvGoQroaLp3uVm_onZaESONQA,257
+modusa/config.py,sha256=bTqK4t00FZqERVITrxW_q284aDDJAa9aMSfFknfR-oU,280
+modusa/decorators.py,sha256=8zeNX_wE37O6Vp0ysR4-WCZaEL8mq8dyCF_I5DHOzks,5905
+modusa/devtools/generate_docs_source.py,sha256=qqxr3UgTeM4iotarQGRN_q2QXwAzGH7ha9bVjs8D4GQ,3409
+modusa/devtools/generate_template.py,sha256=0sT_5-SjMLXyvePRDaIxr1RCz_9v6zFH9OoJqpuD2zI,5204
+modusa/devtools/list_authors.py,sha256=FWBQKOLznVthvMYMASrx2Gw5lqKHEOccQpBisDZ53Dw,24
+modusa/devtools/list_plugins.py,sha256=g-R5hoaCzHfClY_Sfa788IQ9CAKzQGTfyqmthXDZQqw,1729
+modusa/devtools/main.py,sha256=zIB7x6km4RkV3A9P26NWpQberLn_3PWKbABxqAmzlzI,1993
+modusa/devtools/templates/generator.py,sha256=ATEEgf0UtQ_eM_iA7colVBrlilIqViYC1CzNVUlXzRM,449
+modusa/devtools/templates/io.py,sha256=yYU41zMpE204xRsqBxsRqLs3sH1LF6KgtJvzCNKNbhY,388
+modusa/devtools/templates/model.py,sha256=iwmXadLMA4IAMgOEktdCWKZsceLgaaZkTWcJHqjQZzI,954
+modusa/devtools/templates/plugin.py,sha256=MWqrxBxfRKVw2zjEgfAG0RYUAMjuazhqC5PXIb0gJi4,868
+modusa/devtools/templates/test.py,sha256=CjZ_oqwJFhltNYzqfK1pcz1ShgeJXZLOnYpmOawfASs,244
+modusa/devtools/templates/tool.py,sha256=2iQfHbFKtTELPvNoX42rHr9_5lXRrXpwxb9z5OL96Xc,435
+modusa/generators/__init__.py,sha256=xQUsOObRhTEPzdZsBGd4nT_9AWaL8uE_bisFAN_Wp9Q,236
+modusa/generators/audio.py,sha256=91CnBDPZhagfJOx-cDoBBj3NrE92m70PmFmv7T8aQco,4477
+modusa/generators/audio_waveforms.py,sha256=x-r4_kDi2xieQNBCo11qY2uk2bFcvzeNOppfJnj2oYs,6105
+modusa/generators/base.py,sha256=Kd3eAYOU8PDE28hz0uXfnrmgYSK2lGgHcr5NqeExxbE,938
+modusa/generators/ftds.py,sha256=BkELukm5zbDwUxQVoylrlT9irIUUB2ZGfBc5pH5LUDc,6704
+modusa/generators/s1d.py,sha256=M05oU22qkuLd9ycTSoOyfDtC4w2DEBebRZ4VTkUJRQo,5756
+modusa/generators/s2d.py,sha256=kU67dZj4tdIDSUFJeheXm_JKbyHpZZOGmW5jya6w0wo,6874
+modusa/generators/s_ax.py,sha256=4CTFp_KwYnl4HDno-ATpTXOfKR9WEVOV45nwuk2OoVk,2221
+modusa/generators/t_ax.py,sha256=X-XOJuGWw99dPAVsCVzNTfBFr81Vw56aZlGDmcl5q3k,1478
+modusa/generators/tds.py,sha256=eGvzcjXyWaw5NVzM3D098r3xkoMcX8Ma9YoDUdL30Mo,5960
+modusa/main.py,sha256=v9oOhnPcbw8ULfkKRoantEfHw7MqOETJwXC-odx3dnA,25
+modusa/models/__init__.py,sha256=G8sNOnBnTKqPmC4Z46ximBhc_pfBOF_G6AIfxT8DFzw,271
+modusa/models/__pycache__/signal1D.cpython-312.pyc.4443461152,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+modusa/models/audio.py,sha256=IcNx3h8tb5Jt6KZug_TQKM5iufVk3i7Ug37iKG4gsJ0,2411
+modusa/models/base.py,sha256=1qAXj69VsmrjGqShl5b27Jvt7OADHmPY0L9fBtpB_1E,1621
+modusa/models/data.py,sha256=ds5zM0NOCwGImdxNdx27OnVpgKZ6kXUJMYBUqFWshXY,11368
+modusa/models/ftds.py,sha256=5rd-3h1tzuy3OdD-pb66T0trPo77AvseZt3dy1zdZpg,16182
+modusa/models/s1d.py,sha256=Hm2woUn9wcuwq1RYuEwlAWQPOLoRtnJoFD0mofW67mo,15550
+modusa/models/s2d.py,sha256=10XXpZveFW6OY-v7O3xRy6xDNS5lzJi9UjJMqywyuYE,16782
+modusa/models/s_ax.py,sha256=kKUOwZU9wV-w1ZJyOmdkcLMGtSOXA2gYzZ5f1FsHSEg,10793
+modusa/models/t_ax.py,sha256=ZUhvZPUW1TkdZYuUd6Ucm-vsv0JqtZ9yEe3ab67Ma6w,8022
+modusa/models/tds.py,sha256=FAGfibjyyE_lkEuQp-vSCuqQnopOjmy_IXqUjRlg9kc,11677
+modusa/plugins/__init__.py,sha256=r1Bf5mnrVKRIwxboutY1iGzDy4EPQhqpk1kSW7iJj_Q,54
+modusa/plugins/base.py,sha256=Bh_1Bja7fOymFsCgwhXDbV6ys3D8muNrPwrfDrG_G_A,2382
+modusa/tmp.py,sha256=zPwgFVk5Oh6Rp6GUCbWJdkmwo6vYvhSqI35QVhW5xQM,3180
+modusa/tools/__init__.py,sha256=jOFL7PJ1IztN6F7aMdrVKNMTid2yUmoSlSST-WFf0Cc,199
+modusa/tools/audio_converter.py,sha256=415qBoPm2sBIuBSI7m1XBKm0AbmVmPydIPPr-uO8D3c,1778
+modusa/tools/audio_loader.py,sha256=DrCzq0pdiQrUDIG-deLJGcu8EaylO5yRtwT4lr8WSf8,2166
+modusa/tools/audio_player.py,sha256=GP04TWW4jBwQBjANkfR_cJtEy7cIhvbu8RTwnf9hD6E,2817
+modusa/tools/base.py,sha256=C0ESJ0mIfjjRlAkRbSetNtMoOfS6IrHBjexRp3l_Mh4,1293
+modusa/tools/math_ops.py,sha256=ZZ7U4DgqT7cOeE7_Lzi_Qq-48WYfwR9_osbZwTmE9eg,8690
+modusa/tools/plotter.py,sha256=HaiIyP0Ll-Rk8Nw54g-R-AY9aAZxSAtnviYFnfuln_w,10552
+modusa/tools/youtube_downloader.py,sha256=hB_X8-7nOHXOlxg6vv3wyhBLoAsWyomrULP6_uCQL7s,1698
+modusa/utils/.DS_Store,sha256=nLXMwF7QJNuglLI_Gk74F7vl5Dyus2Wd74Mgowijmdo,6148
+modusa/utils/__init__.py,sha256=1oLL20yLB1GL9IbFiZD8OReDqiCpFr-yetIR6x1cNkI,23
+modusa/utils/config.py,sha256=cuGbqbovx5WDQq5rw3hIKcv3CnE5NttjacSOWnP1yu4,576
+modusa/utils/excp.py,sha256=L9vhaGjKpv9viJYdmC9n5ndmk2GVbUBuFyZyhAQZmWY,906
+modusa/utils/logger.py,sha256=K0rsnObeNKCxlNeSnVnJeRhgfmob6riB2uyU7h3dDmA,571
+modusa/utils/np_func_cat.py,sha256=TyIFgRc6bARRMDnZxlVURO5Z0I-GWhxRONYyIv-Vwxs,1007
+modusa/utils/plot.py,sha256=s_vNdxvKfwxEngvJPgrF1PcmxZNnNaaXPViHWjyjJ-c,5335
+modusa-0.3.dist-info/RECORD,,

modusa/engines/__init__.py

@@ -1,3 +0,0 @@
-#!/usr/bin/env python3
-
-from .base import ModusaEngine

modusa/engines/base.py

@@ -1,14 +0,0 @@
-#!/usr/bin/env python3
-
-from abc import ABC, abstractmethod
-from typing import Any
-
-class ModusaEngine(ABC):
-	"""
-	Base class for all core logic components in the Modusa system.
-	Every subclass must implement the `run` method.
-	"""
-	
-	@abstractmethod
-	def run(self, *args, **kwargs) -> Any:
-		pass

modusa/io/__init__.py

@@ -1,9 +0,0 @@
-#!/usr/bin/env python3
-
-from .base import ModusaIO
-
-from .audio_loader import AudioLoader
-from .audio_converter import AudioConverter
-from .youtube_downloader import YoutubeDownloader
-from .plotter import Plotter
-from .audio_player import AudioPlayer

modusa/io/audio_converter.py

@@ -1,76 +0,0 @@
-#!/usr/bin/env python3
-
-
-from modusa import excp
-from modusa.decorators import validate_args_type
-from modusa.io.base import ModusaIO
-from typing import Any
-import subprocess
-from pathlib import Path
-
-
-class AudioConverter(ModusaIO):
-	"""
-	Converts audio using FFmpeg.
-
-	Note
-	----
-	- Use `convert()` to perform the actual format conversion.
-	- Requires FFMPEG to be installed on the system.
-	"""
-	
-	#--------Meta Information----------
-	_name = "Audio Converter"
-	_description = "Convert audio files using ffmpeg"
-	_author_name = "Ankit Anand"
-	_author_email = "ankit0.anand0@gmail.com"
-	_created_at = "2025-07-05"
-	#----------------------------------
-	
-	@staticmethod
-	@validate_args_type()
-	def convert(inp_audio_fp: str | Path, output_audio_fp: str | Path) -> Path:
-		"""
-		Converts an audio file from one format to another using FFmpeg.
-
-		.. code-block:: python
-			
-			from modusa.engines import AudioConverter
-			converted_audio_fp = AudioConverter.convert(
-				inp_audio_fp="path/to/input/audio.webm", 
-				output_audio_fp="path/to/output/audio.wav"
-			)
-
-		Parameters
-		----------
-		inp_audio_fp: str | Path
-			Filepath of audio to be converted.
-		output_audio_fp: str | Path
-			Filepath of the converted audio. (e.g. name.mp3)
-
-		Returns
-		-------
-		Path:
-			Filepath of the converted audio.
-
-		Note
-		----
-		- The conversion takes place based on the extensions of the input and output audio filepath.
-		"""
-		inp_audio_fp = Path(inp_audio_fp)
-		output_audio_fp = Path(output_audio_fp)
-
-		cmd = [
-			"ffmpeg",
-			"-y",  # Overwrite output
-			"-i", str(inp_audio_fp),
-			"-vn",  # No video
-			str(output_audio_fp)
-		]
-
-		try:
-			subprocess.run(cmd, check=True, stdout=subprocess.DEVNULL, stderr=subprocess.STDOUT)
-		except subprocess.CalledProcessError:
-			raise RuntimeError(f"FFmpeg failed to convert {inp_audio_fp} to {output_audio_fp}")
-			
-		return output_audio_fp

modusa/io/audio_loader.py

@@ -1,214 +0,0 @@
-#!/usr/bin/env python3
-
-from modusa.io import ModusaIO
-from modusa.signals import AudioSignal
-from modusa.decorators import validate_args_type
-from pathlib import Path
-import tempfile
-import numpy as np
-
-class AudioLoader(ModusaIO):
-	"""
-	Loads audio from various sources like filepath, YouTube, etc.
-	
-	Note
-	----
-	- All `from_` methods return :class:`~modusa.signals.AudioSignal` instance.
-	
-	"""
-	
-	#--------Meta Information----------
-	_name = "Audio Loader"
-	_description = "Loads audio from various sources."
-	_author_name = "Ankit Anand"
-	_author_email = "ankit0.anand0@gmail.com"
-	_created_at = "2025-07-05"
-	#----------------------------------
-	
-	def __init__(self):
-		super().__init__()
-
-	@staticmethod
-	@validate_args_type()
-	def from_youtube(url: str, sr: int | None = None) -> "AudioSignal":
-		"""
-		Loads audio from youtube url using :class:`~modusa.io.YoutubeDownloader`,
-		:class:`~modusa.io.AudioConverter` and `librosa`.
-
-		.. code-block:: python
-			
-			from modusa.io import AudioSignalLoader
-		
-			# From youtube
-			audio_signal = AudioSignalLoader.from_youtube(
-				url="https://www.youtube.com/watch?v=lIpw9-Y_N0g", 
-				sr=None
-			)
-
-		PARAMETERS
-		----------
-		url: str
-			Link to the YouTube video.
-		sr: int
-			Sampling rate to load the audio in.
-		
-		Returns
-		-------
-		
-		AudioSignal:
-			`Audio signal` instance with loaded audio content from YouTube.
-		"""
-
-		from modusa.io import YoutubeDownloader, AudioConverter
-		import librosa
-		
-		# Download the audio in temp directory using tempfile module
-		with tempfile.TemporaryDirectory() as tmpdir:
-			audio_fp: Path = YoutubeDownloader.download(url=url, content_type="audio", output_dir=Path(tmpdir))
-			
-			# Convert the audio to ".wav" form for loading
-			wav_audio_fp: Path = AudioConverter.convert(inp_audio_fp=audio_fp, output_audio_fp=audio_fp.with_suffix(".wav"))
-			
-			# Load the audio in memory and return that
-			audio_data, audio_sr = librosa.load(wav_audio_fp, sr=sr)
-		
-		audio = AudioSignal(y=audio_data, sr=audio_sr, title=audio_fp.stem)
-
-		return audio
-	
-	@staticmethod
-	@validate_args_type()
-	def from_fp(fp: str | Path, sr: int | None = None) -> AudioSignal:
-		"""
-		Loads audio from a filepath using `librosa`.
-
-		.. code-block:: python
-			
-			from modusa.io import AudioSignalLoader
-			
-			# From file
-			audio_signal = AudioSignalLoader.from_fp(
-				fp="path/to/audio.wav", 
-				sr=None
-			)
-
-		Parameters
-		----------
-		fp: str | Path
-			Local filepath of the audio.
-		sr: int | None
-			Sampling rate to load the audio in.
-		
-		Returns
-		-------
-		AudioSignal
-			`Audio signal` instance with loaded audio content from filepath.
-		
-		"""
-		import librosa
-		import warnings
-		warnings.filterwarnings("ignore", message="pkg_resources is deprecated as an API.")
-		
-		fp = Path(fp)
-		y, sr = librosa.load(fp, sr=sr)
-		
-		audio_signal = AudioSignal(y=y, sr=sr, title=fp.name)
-		
-		return audio_signal
-	
-	
-	@staticmethod
-	def from_array(y: np.ndarray, t: np.ndarray | None = None) -> AudioSignal:
-		"""
-		Loads audio from numpy arrays.
-
-		.. code-block:: python
-			
-			from modusa.io import AudioSignalLoader
-			import numpy as np
-			
-			# From numpy array
-			audio_signal = AudioSignalLoader.from_array(
-				x=np.random.random((100, )),
-				t = None # Automatically creates time index (integer)
-			)
-
-		Parameters
-		----------
-		y: np.ndarray
-			Data of the audio signal.
-		t: np.ndarray | None
-			Corresponding time stamps of the audio signal.
-		
-		Returns
-		-------
-		AudioSignal
-			`Audio signal` instance with loaded audio content from arrays.
-		"""
-		
-		return  AudioSignal(y=y, t=t)
-	
-	@staticmethod
-	def from_array_with_sr(y: np.ndarray, sr: int) -> AudioSignal:
-		"""
-		Loads audio with a given sampling rate.
-	
-		.. code-block:: python
-			
-			from modusa.io import AudioSignalLoader
-			import numpy as np
-			
-			# From numpy array
-			audio_signal = AudioSignalLoader.from_array_with_sr(
-				x=np.random.random((100, )),
-				sr = 100 # Automatically generates time index
-			)
-
-		Parameters
-		----------
-		y: np.ndarray
-			Data of the audio signal.
-		sr: int
-			Sampling rate of the audio signal.
-		
-		Returns
-		-------
-		AudioSignal
-			`Audio signal` instance with loaded audio content from sampling rate.
-		"""
-		
-		return AudioSignal(y=y, sr=sr)
-	
-	@staticmethod
-	def from_list(y: list, t: list) -> AudioSignal:
-		"""
-		Loads `AudioSignal` instance from python list.
-		
-		.. code-block:: python
-			
-			from modusa.io import AudioSignalLoader
-			
-			# From list
-			audio_signal = AudioSignalLoader.from_list(
-				y=[1, 2, 3, 2, 3],
-				t = [0.1, 0.2, 0.3, 0.4, 0.5]
-			)
-
-		Parameters
-		----------
-		y: list
-			Data of the audio signal.
-		t: np.ndarray | None
-			Corresponding time stamps of the audio signal.
-		
-		Returns
-		-------
-		AudioSignal
-			`Audio signal` instance with loaded audio content from python list.
-		"""
-		y = np.array(y)
-		t = np.array(t)
-		
-		return AudioSignal(y=y, t=t)
-		
-		

modusa/io/audio_player.py

@@ -1,72 +0,0 @@
-#!/usr/bin/env python3
-
-
-from modusa import excp
-from modusa.decorators import validate_args_type
-from modusa.io import ModusaIO
-from IPython.display import display, HTML, Audio
-import numpy as np
-
-class AudioPlayer(ModusaIO):
-	"""
-	
-	"""
-	
-	#--------Meta Information----------
-	_name = "Audio Player"
-	_description = ""
-	_author_name = "Ankit Anand"
-	_author_email = "ankit0.anand0@gmail.com"
-	_created_at = "2025-07-08"
-	#----------------------------------
-	
-	@staticmethod
-	def play(
-		y: np.ndarray,
-		sr: int,
-		regions: list[tuple[float, float]] | None = None,
-		title: str | None = None
-	) -> None:
-		"""
-		Plays audio clips for given regions in Jupyter Notebooks.
-
-		Parameters
-		----------
-		y : np.ndarray
-			Audio time series.
-		sr : int
-			Sampling rate.
-		regions : list of (float, float), optional
-			Regions to extract and play (in seconds).
-		title : str, optional
-			Title to display above audio players.
-
-		Returns
-		-------
-		None
-		"""
-		if not AudioPlayer._in_notebook():
-			return
-		
-		if title:
-			display(HTML(f"<h4>{title}</h4>"))
-			
-		if regions:
-			for i, (start_sec, end_sec) in enumerate(regions):
-				start_sample = int(start_sec * sr)
-				end_sample = int(end_sec * sr)
-				clip = y[start_sample:end_sample]
-				
-				display(HTML(f"<b>Clip {i+1}</b>: {start_sec:.2f}s → {end_sec:.2f}s"))
-				display(Audio(data=clip, rate=sr))
-		else:
-			display(Audio(data=y, rate=sr))
-			
-	@staticmethod
-	def _in_notebook() -> bool:
-		try:
-			from IPython import get_ipython
-			shell = get_ipython()
-			return shell and shell.__class__.__name__ == "ZMQInteractiveShell"
-		except ImportError:
-			return False

modusa/io/base.py

@@ -1,43 +0,0 @@
-#!/usr/bin/env python3
-
-from abc import ABC, abstractmethod
-
-class ModusaIO(ABC):
-	"""
-	Base class for all I/O components: loaders, savers, recorders, etc.
-	
-	>>> modusa-dev create io
-
-	.. code-block:: python
-		
-		# General template of a subclass of ModusaIO
-		from modusa.io import ModusaIO
-
-		class MyCustomIOClass(ModusaIO):
-			#--------Meta Information----------
-			_name = "My Custom I/O"
-			_description = "My custom class for I/O."
-			_author_name = "Ankit Anand"
-			_author_email = "ankit0.anand0@gmail.com"
-			_created_at = "2025-07-06"
-			#----------------------------------
-			
-			@staticmethod
-			def do_something():
-				pass
-		
-	
-	Note
-	----
-	- This class is intended to be subclassed by any IO related tools built for the modusa framework.
-	- In order to create an IO tool, you can use modusa-dev CLI to generate an IO template.
-	- It is recommended to treat subclasses of ModusaIO as namespaces and define @staticmethods with control parameters, rather than using instance-level __init__ methods.
-	"""
-	
-	#--------Meta Information----------
-	_name: str = "Modusa I/O"
-	_description: str = "Base class for any I/O in the Modusa framework."
-	_author_name = "Ankit Anand"
-	_author_email = "ankit0.anand0@gmail.com"
-	_created_at = "2025-07-06"
-	#----------------------------------